Documentation Index
Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
Use this file to discover all available pages before exploring further.
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
});
| 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 |
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 |
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
