> ## 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.

# Concepts

> Tell's three data protocols — events, logs, and snapshots — and how they work together.

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.

```javascript theme={null}
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:

| Type         | What it does                                              |
| ------------ | --------------------------------------------------------- |
| **track**    | Record a user action — `page_view`, `sign_up`, `purchase` |
| **identify** | Link a device to a known user ID when they log in         |
| **session**  | Device and session context (SDKs send this automatically) |
| **group**    | Associate a user with a company or team                   |
| **revenue**  | Track a purchase with amount, currency, and order ID      |
| **alias**    | Merge 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](/tracking/events-and-properties) | [Users & Identity](/tracking/users-and-identity) | [Sessions](/tracking/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.

```javascript theme={null}
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](/tracking/logs)

## Snapshots

Snapshots pull data from services outside your app on a schedule. You connect a service like GitHub or Shopify, and Tell pulls metrics over time automatically.

```toml theme={null}
[[plugins]]
name = "github"
entity = "your-org/your-repo"
config.token = "${GITHUB_TOKEN}"
```

This captures stars, forks, issues, and commits on a schedule — a time series of your repository's growth without writing any code. Shopify works the same way 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: [Integrations](/tracking/integrations/overview)

## 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 an integration — 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](/pipeline/overview)

## What's next

* [Architecture](/getting-started/architecture) — deployment topologies from single node to distributed
* [Quickstart](/getting-started/quickstart) — send your first event in under 5 minutes
* [What to Track](/getting-started/what-to-track) — choosing between events, logs, and snapshots