Skip to main content
Tell has three data protocols. Each handles a different kind of signal, but they all flow through the same server and can be queried together.

​
Events

Events are your product analytics — the things users do in your app. Page views, signups, purchases, feature toggles. If you’ve used Mixpanel, Segment, or PostHog, this works the same way. 
tell.track('purchase', { plan: 'pro', amount: 49.99 });
Every event has a name and optional properties — key-value pairs you can use for breakdowns, filters, and aggregations. “Show me purchases broken down by plan” or “daily active users by country.” Within the events protocol, there are several message types:
TypeWhat it does
trackRecord a user action — page_view, sign_up, purchase
identifyLink a device to a known user ID when they log in
sessionDevice and session context (SDKs send this automatically)
groupAssociate a user with a company or team
revenueTrack a purchase with amount, currency, and order ID
aliasMerge two user identities across devices
Most of the time you’ll use track and identify. Sessions are managed automatically by the SDK — when a user opens your app, a session starts and groups all their events together. The rest are for specific use cases. Read more: Events & Properties | Users & Identity | Sessions

​
Logs

Logs are your application’s internal voice — errors, warnings, debug info. Tell is a full structured logging framework with 9 severity levels, service tags, and arbitrary metadata. 
tell.log('error', 'Payment failed', {
  service: 'billing',
  error_code: 'CARD_DECLINED',
  user_id: 'user-123'
});
The same SDK that sends your product analytics also sends your logs. They’re stored separately, but because they share a pipeline and a server, you can correlate them. A user reports a bug — you see their event trail and the errors your app threw during that session. Read more: Logs

​
Snapshots

Snapshots pull data from services outside your app on a schedule. You configure a connector, and Tell reaches out to APIs like GitHub or Shopify to capture metrics over time. 
[connectors.my_repo]
type = "github"
entities = ["your-org/your-repo"]
schedule = "0 0 */6 * * *"
This captures stars, forks, issues, and commits every 6 hours — a time series of your repository’s growth without writing any integration code. Shopify connectors do the same for orders, revenue, and customers. Snapshots are how you get the full business picture alongside your product analytics. Track what users do and how the business responds. Read more: Connectors

​
Properties

Properties are the key-value pairs attached to events and logs. They’re what make your data queryable.
  • Event properties: plan, amount, source, page_url
  • User traits: email, company, signup_date (set via identify)
  • Log fields: service, level, error_code
Any metric can be broken down by any property. Any property can be filtered with 15 operators — equals, contains, greater than, regex, and more.

​
The pipeline

When data arrives — from an SDK, an HTTP request, or a connector — it passes through a pipeline before being stored. The pipeline routes data to the right destination, and optionally filters, redacts PII, or transforms it in flight. For most setups you don’t need to configure this. The defaults work. When you need more control — routing logs to disk and events to ClickHouse, redacting emails before storage, filtering out health checks — the pipeline is fully configurable. Read more: Pipeline Overview

​
What’s next

  • Quickstart — send your first event in under 5 minutes
  • What to Track — choosing between events, logs, and snapshots
  • SDKs — language-specific integration guides