Skip to main content
Logs are a separate protocol from events. Events track what users do (product analytics). Logs track what your application does (errors, warnings, system behavior). They use the same SDKs and the same pipeline, but they have a different schema and different semantics.

​
Sending a log

tell.log('error', 'Connection to payment gateway timed out', {
  service: 'billing',
  error: 'GATEWAY_TIMEOUT',
  retry_count: 3
});
Every log entry has:
FieldRequiredDescription
levelYesSeverity level (see below)
messageYesHuman-readable log message
serviceYesService or application name
dataNoStructured key-value metadata

​
Severity levels

Tell uses RFC 5424 severity levels plus trace:
LevelWhen to use
emergencySystem is unusable
alertImmediate action needed
criticalCritical conditions
errorError that needs attention
warningSomething unexpected
noticeNormal but significant
infoInformational (default)
debugDebug details
traceDetailed tracing
SDKs provide convenience methods for each level: 
tell.logError('billing', 'Payment declined', { error: 'CARD_DECLINED' });
tell.logWarning('auth', 'Rate limit approaching', { current: 450, limit: 500 });
tell.logInfo('deploy', 'Service restarted', { version: '2.1.0' });

​
How logs differ from events

Logs and events are different protocols with different schemas. Understanding the differences helps you use each one correctly.
EventsLogs
PurposeWhat users doWhat your app does
User IDRequiredNot included
Device IDAutomaticNot included
Session IDAutomaticIncluded (for correlation)
Super propertiesYes (register())No
Identify / Group / RevenueYesNo
Device contextAutomatic on mobileNo
Service nameNoRequired
Severity levelNoRequired
Events are user-centric — every event is tied to a device and a user. Logs are infrastructure-centric — they’re tied to a service and a source, not a user.

​
Session correlation

Logs share a session ID with events. On mobile SDKs, this happens automatically — the same session that groups a user’s events also tags their logs. This lets you correlate what a user was doing (events) with what the app was doing (logs) during the same session. On server-side SDKs, you control the session ID. You can set it to match a request ID, a job ID, or any identifier that makes sense for your correlation needs. 
// Server-side: set session for correlation
client.ResetSession() // generates new session ID
client.Track("checkout_started", userID, props)
client.LogError("billing", "Payment timeout", data) // same session ID

​
Structured data

The data field accepts arbitrary key-value pairs — strings, numbers, booleans, nested objects. Use it for context that helps you debug: 
tell.logError('api', 'Request failed', {
  method: 'POST',
  path: '/api/v1/orders',
  status: 502,
  duration_ms: 12340,
  upstream: 'payment-service'
});

​
Pipeline processing

Logs flow through the same pipeline as events — routing, transforms, and sinks all apply. You can:
  • Route logs to a different sink than events (e.g., logs to disk, events to ClickHouse)
  • Redact PII from log messages using the redact transform
  • Extract patterns from logs using the pattern transform for anomaly detection
  • Filter out noisy log levels using the filter transform
See Pipeline Overview for configuration details.

​
What’s next