Telemetry

Electric provides telemetry data — such as traces, logs, and metrics — for real-time system monitoring.

Metrics

Metrics are reported in StatsD and Prometheus formats. To configure Electric to expose metric information in those formats use the following environment variables.

VARIABLE	Description
ELECTRIC_STATSD_HOST	The address of the StatsD server
ELECTRIC_PROMETHEUS_PORT	The scrape port for Prometheus

You can get the current status of the service by calling the http://electric-hostname:PROMETHUES_PORT/metrics endpoint.

Only enable Prometheus if you are scraping it

When ELECTRIC_PROMETHEUS_PORT is set, Electric starts a Prometheus reporter that must be scraped regularly — for example by a Prometheus server polling the /metrics endpoint on an interval. Distribution (histogram) metrics buffer their observations in memory between scrapes and are only aggregated when the endpoint is scraped. If you enable the port but never scrape it, that buffer grows without bound and will eventually exhaust memory and crash the service.

Only set ELECTRIC_PROMETHEUS_PORT if a Prometheus-compatible scraper is actively collecting from the endpoint. If you only use OpenTelemetry, leave it unset.

OpenTelemetry

Traces are exported using the OpenTelemetry Protocol (OTLP). You can configure the OpenTelemetry Exporter for Electric using the following environment variables.

VARIABLE	Type	Description
ELECTRIC_OTLP_ENDPOINT	URL	An OpenTelemetry collector endpoint url.
ELECTRIC_HNY_API_KEY	string	API key for exporting to Honeycomb.io.
ELECTRIC_HNY_DATASET	string	Dataset name for Honeycomb.io.
ELECTRIC_OTEL_DEBUG	boolean	Enable or disable debug logging of telemetry data to stdout.

Electric enables export of telemetry data when it is configured with an ELECTRIC_OTLP_ENDPOINT.

There is builtin support for Honeycomb.io: telemetry data can be exported directly to it by specifying ELECTRIC_OTLP_ENDPOINT=https://api.honeycomb.io and adding at least the ELECTRIC_HNY_API_KEY configuration option.

In order to use other telemetry data collectors, you'll need to run the OpenTelemetry Collector and include the exporter of choice in its configuration file along with any required credentials, then use Collector's URL as the value for ELECTRIC_OTLP_ENDPOINT.

Electric always adds the following resource attributes to events:

%{service: %{name: service_name, version: version}, instance: %{id: instance_id}}

Attributes service_name and instance_id can be overridden with ELECTRIC_SERVICE_NAME and ELECTRIC_INSTANCE_ID respectively. By default, instance_id is a uuid.

Electric will also load additional resource attributes from OTEL_RESOURCE_ATTRIBUTES. Learn more about resource attributes in the OpenTelemetry documentation.

Sentry

Electric includes built-in support for Sentry error tracking. When enabled, errors are automatically captured and reported to your Sentry project, including source code context in stack traces.

To enable Sentry, set the SENTRY_DSN environment variable to your Sentry project's DSN:

VARIABLE	Type	Description
SENTRY_DSN	string	DSN for your Sentry project (optional)

When configured, Electric will:

• Capture all error-level log messages and report them to Sentry
• Include source code context in stack traces for easier debugging
• Tag errors with stack context for multi-tenant debugging

INFO

Sentry support requires Electric to be built with telemetry enabled. The official Docker images (electricsql/electric) include telemetry by default.

Example

You can find an example of a docker compose that runs Electric with an OpenTelemetry Collector agent that sends telemetry data to Honeycomb under packages/sync-service/dev.

Set ELECTRIC_HNY_DATASET and ELECTRIC_HNY_API_KEY environment variables in a terminal session and run docker compose in it like so:

docker compose -f docker-compose-otel.yml up