Data flows and telemetry in self-hosted Lightdash

​

Summary

• Warehouse credentials, dbt or Lightdash YAML definitions, generated SQL, query results, dashboard and chart definitions, and underlying warehouse data are processed inside your deployment. None of these are sent to Lightdash through product telemetry.
• Product telemetry is enabled by default and points at Lightdash’s RudderStack endpoint (https://analytics.lightdash.com) using a built-in write key. It can be disabled with a single environment variable, or redirected to your own RudderStack instance.
• Enterprise Edition validates its license key against Keygen on every server start. The request contains the license key only — no warehouse credentials, no query text, no business data. See License validation request for the exact payload.
• Optional integrations (SSO, SMTP, Slack, GitHub, object storage, AI providers, MCP, sandbox providers, Sentry, and the organization roadmap) talk directly to the endpoints you configure. They are not proxied through Lightdash Cloud.

​

Three telemetry configurations

​

Configuration 1: default Lightdash telemetry

• Endpoint: https://analytics.lightdash.com
• Write key: built into the release
• Enabled by default: yes, on every fresh install
• Applies to: the backend, the scheduler, and the browser (the frontend loads its RudderStack config from the backend’s /api/v1/health response)

​

Configuration 2: disable outbound RudderStack telemetry

RUDDERSTACK_ANALYTICS_DISABLED=true

• The backend LightdashAnalytics.track(), identify(), and group() calls short-circuit and send nothing.
• The /api/v1/health response returns an empty rudder block, so the browser skips rudder-sdk-js initialization and emits no client-side events.
• RUDDERSTACK_ANALYTICS_DISABLED=true takes precedence over RUDDERSTACK_WRITE_KEY and RUDDERSTACK_DATA_PLANE_URL.

• The backend container (lightdash-headless / lightdash)
• The scheduler container (scheduler.enabled: true)
• Any NATS worker containers (warehouseNatsWorker, preAggregateWorker)

# lightdash/lightdash Helm chart
extraEnv:
  - name: RUDDERSTACK_ANALYTICS_DISABLED
    value: "true"

scheduler:
  extraEnv:
    - name: RUDDERSTACK_ANALYTICS_DISABLED
      value: "true"

warehouseNatsWorker:
  extraEnv:
    - name: RUDDERSTACK_ANALYTICS_DISABLED
      value: "true"

services:
  lightdash:
    image: lightdash/lightdash:latest
    environment:
      RUDDERSTACK_ANALYTICS_DISABLED: "true"

  scheduler:
    image: lightdash/lightdash:latest
    environment:
      RUDDERSTACK_ANALYTICS_DISABLED: "true"

​

Configuration 3: send telemetry to your own RudderStack

RUDDERSTACK_WRITE_KEY=your-write-key
RUDDERSTACK_DATA_PLANE_URL=https://your-rudderstack.example.com

• The backend uses these values in place of the built-in ones.
• The browser reads them from /api/v1/health and initializes rudder-sdk-js against your endpoint.
• Events go to your RudderStack destination instead of Lightdash’s. Lightdash never sees them.
• If RUDDERSTACK_ANALYTICS_DISABLED=true is also set, disable wins — no events are sent anywhere.

​

Telemetry payload

​

Common context on every event

​

Event categories

​

User-level tracking anonymization

• The is_tracking_anonymized: true flag is set on the user record and included in identify/update events.
• The user.updated, user.verified, and user.deleted events drop email, firstName, and lastName.
• The userId and resource identifiers (organizationId, projectId, chart/dashboard UUIDs) are still sent — anonymization operates at the user-name/email level, not at the identifier level.

​

Not sent through RudderStack telemetry

• Warehouse credentials or authentication secrets. Connection strings, keys, and tokens live in LIGHTDASH_SECRET-encrypted rows in Postgres and are never included in event payloads.
• dbt project files or complete semantic-layer definitions. Warehouse type and dbtConnectionType are included; the manifest, .yml model files, and metric definitions are not.
• Generated SQL or SQL Runner query text. Query events carry an ID, structural counts, timings, and warehouse type — never the SQL string.
• Query results, row values, or warehouse records. Query events carry totalRowCount and columnsCount — never row data.
• Complete dashboard or chart definitions. Create/update events carry structural counts (metrics, dimensions, filters, series types), the chart type, and the chart or dashboard title and description. They do not carry the full config JSON, tile layout, or filter values.
• AI prompt text, conversation text, or model responses. ai.usage events carry token counts, provider, model, feature, and IDs (aiAgentId, threadId, promptId, organizationId, projectId). They do not carry prompt or completion text.
• Integration credentials or application secrets. OAuth tokens, Slack bot tokens, GitHub app credentials, SMTP passwords, LIGHTDASH_LICENSE_KEY, LIGHTDASH_SECRET, and AI-provider API keys are never sent.

• Chart, dashboard, space, and scheduler titles and descriptions on create/update events.
• Explore name (exploreName) and virtual view ID on query events.
• User email, first name, last name on user identify/update events — unless the user has enabled tracking anonymization.
• Short server-side error messages on error events (typed exception messages, not stack traces of user data).
• Stable UUIDs for organizations, projects, users, charts, dashboards, spaces, schedulers, queries, and AI agents.

​

Enterprise license validation

​

License validation request

• Endpoint: POST https://api.keygen.sh/v1/accounts/1ae7d3a8-4665-44e4-989d-9de54c84761a/licenses/actions/validate-key
• Timing: on server start and roughly once every 24 hours from the process cache
• Initiator: the Lightdash backend and any process that instantiates LicenseClient (backend, scheduler, workers)
• Request headers: Content-Type: application/json, Accept: application/json
• Request body:
  {
    "meta": {
      "key": "<value of LIGHTDASH_LICENSE_KEY>"
    }
  }
  
• Response: validity, human-readable detail, and a status code. No code or configuration is pulled during validation.

​

Related systems

​

Egress matrix

​

Security-review checklist

​

Further reading

• Environment variables — Analytics & Event Tracking
• Enterprise features and license validation
• Production deployment checklist — includes the default egress policy
• Usage Analytics dashboards and query tags
• Prometheus and OpenTelemetry metrics
• AI agents and AI providers
• Data apps sandboxes
• MCP
• Slack
• GitHub
• External object storage
• Organization roadmap
• Instance health