Telemetry

Tuist provides three complementary observability signals: metrics (Prometheus), traces (OpenTelemetry), and logs (Loki-compatible). All three are optional and can be enabled independently.

Distributed tracing (OpenTelemetry)#

Tuist supports OpenTelemetry for distributed tracing. When enabled, the server emits traces for HTTP requests (Phoenix and Bandit), database queries (Ecto), outgoing HTTP calls (Finch), and Broadway message processing. These traces let you understand request latency, identify slow queries, and follow requests across services.

Configuration#

Set the following environment variable to enable trace export:

Environment variable	Description	Required	Default	Example
`TUIST_OTEL_EXPORTER_OTLP_ENDPOINT`	The gRPC endpoint of an OpenTelemetry Collector (e.g. Grafana Alloy, Jaeger, or any OTLP-compatible collector)	No		`http://localhost:4317`

When this variable is not set, tracing is disabled and adds no overhead.

Instrumented libraries#

The following libraries are automatically instrumented when tracing is enabled:

Bandit -- HTTP server connection spans
Phoenix -- Request lifecycle spans (controller actions, LiveView)
Ecto -- Database query spans with query metadata
Finch -- Outgoing HTTP client request spans
Broadway -- Message processing pipeline spans

Example setup with Grafana Alloy#

If you use Grafana Alloy as your collector, configure it to receive OTLP traces and forward them to your tracing backend (e.g. Grafana Cloud Tempo):

plaintext

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }
  output {
    traces = [otelcol.exporter.otlp.your_backend.input]
  }
}

Then set TUIST_OTEL_EXPORTER_OTLP_ENDPOINT to point to the Alloy instance, e.g. http://alloy:4317.

Log forwarding (Loki)#

Tuist can forward application logs to a Loki-compatible endpoint. This allows you to centralize logs alongside your metrics and traces for a complete observability picture. Logs are pushed via the Loki HTTP push API (/loki/api/v1/push) and include labels for app, env, and level.

Configuration#

Environment variable	Description	Required	Default	Example
`TUIST_LOKI_URL`	The base URL of a Loki-compatible push API endpoint	No		`http://localhost:3100`

When this variable is not set, log forwarding is disabled.

Example setup with Grafana Alloy#

Grafana Alloy can act as a local log relay using its loki.source.api component:

plaintext

loki.source.api "default" {
  http {
    listen_address = "0.0.0.0"
    listen_port    = 3100
  }
  forward_to             = [loki.write.your_backend.receiver]
  use_incoming_timestamp = true
}

loki.write "your_backend" {
  endpoint {
    url = "https://your-loki-instance/loki/api/v1/push"
    basic_auth {
      username = "your-username"
      password = "your-password"
    }
  }
}

Then set TUIST_LOKI_URL=http://alloy:3100.

You can also point TUIST_LOKI_URL directly at a Loki instance if it exposes the push API.

Prometheus metrics#

You can ingest metrics gathered by the Tuist server using Prometheus and a visualization tool such as Grafana to create a custom dashboard tailored to your needs. The Prometheus metrics are served via the /metrics endpoint on port 9091. The Prometheus' scrape_interval should be set as less than 10_000 seconds (we recommend 30 seconds to balance observability with metrics ingestion costs).

PostHog analytics#

Tuist integrates with PostHog for user behavior analytics and event tracking. This allows you to understand how users interact with your Tuist server, track feature usage, and gain insights into user behavior across the marketing site, dashboard, and API documentation.

Configuration#

PostHog integration is optional and can be enabled by setting the appropriate environment variables. When configured, Tuist will automatically track user events, page views, and user journeys.

Environment variable	Description	Required	Default	Example
`TUIST_POSTHOG_API_KEY`	Your PostHog project API key	No		`phc_fpR9c0Hs5H5VXUsupU1I0WlEq366FaZH6HJR3lRIWVR`
`TUIST_POSTHOG_URL`	The PostHog API endpoint URL	No		`https://eu.i.posthog.com`

Analytics Enablement

Analytics are only enabled when both TUIST_POSTHOG_API_KEY and TUIST_POSTHOG_URL are configured. If either variable is missing, no analytics events will be sent.

Features#

When PostHog is enabled, Tuist automatically tracks:

User identification: Users are identified by their unique ID and email address
User aliasing: Users are aliased by their account name for easier identification
Group analytics: Users are grouped by their selected project and organization for segmented analytics
Page sections: Events include super properties indicating which section of the application generated them:
- marketing - Events from marketing pages and public content
- dashboard - Events from the main application dashboard and authenticated areas
- api-docs - Events from API documentation pages
Page views: Automatic tracking of page navigation using Phoenix LiveView
Custom events: Application-specific events for feature usage and user interactions

Privacy considerations#

For authenticated users, PostHog uses the user's unique ID as the distinct identifier and includes their email address
For anonymous users, PostHog uses memory-only persistence to avoid storing data locally
All analytics respect user privacy and follow data protection best practices
PostHog data is processed according to PostHog's privacy policy and your configuration

Elixir metrics#

By default we include metrics of the Elixir runtime, BEAM, Elixir, and some of the libraries we use. The following are some of the metrics you can expect to see:

We recommend checking those pages to know which metrics are available and how to use them.

Runs metrics#

A set of metrics related to Tuist Runs.

`tuist_runs_total` (counter)#

The total number of Tuist Runs.

Tag	Description
`name`	The name of the `tuist` command that was run, such as `build`, `test`, etc.
`is_ci`	A boolean indicating if the executor was a CI or a developer's machine.
`status`	`0` in case of `success`, `1` in case of `failure`.

Tag	Description
`object_key`	The lookup key of the object in the remote storage.
`part_number`	The part number of the object being uploaded.
`upload_id`	The upload ID of the multipart upload.

Tag	Description
`cli_version`	The version of the Tuist CLI that encountered the error.
`reason`	The reason for the token refresh error, such as `invalid_token_type` or `invalid_token`.

Tag	Description
`repo`	The repository that emitted the metric, such as `postgres`, `clickhouse_read`, or `clickhouse_write`.
`database`	The backing database type, such as `postgres` or `clickhouse`.