Logs

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:

Field	Required	Description
level	Yes	Severity level (see below)
message	Yes	Human-readable log message
service	Yes	Service or application name
data	No	Structured key-value metadata

Severity levels

Tell uses RFC 5424 severity levels plus trace:

Level	When to use
`emergency`	System is unusable
`alert`	Immediate action needed
`critical`	Critical conditions
`error`	Error that needs attention
`warning`	Something unexpected
`notice`	Normal but significant
`info`	Informational (default)
`debug`	Debug details
`trace`	Detailed 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.

	Events	Logs
Purpose	What users do	What your app does
User ID	Required	Not included
Device ID	Automatic	Not included
Session ID	Automatic	Included (for correlation)
Super properties	Yes (`register()`)	No
Identify / Group / Revenue	Yes	No
Device context	Automatic on mobile	No
Service name	No	Required
Severity level	No	Required

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

Events & Properties — the product analytics protocol
Integrations — pull external data automatically
SDKs — language-specific integration guides

Getting Started

Tracking

Pipeline

Analytics

Installing

Sending a log

Severity levels

How logs differ from events

Session correlation

Structured data

Pipeline processing

What’s next

​Sending a log

​Severity levels

​How logs differ from events

​Session correlation

​Structured data

​Pipeline processing

​What’s next

Sending a log

Severity levels

How logs differ from events

Session correlation

Structured data

Pipeline processing

What’s next