|
| 1 | +# dagster_runs_to_otlp_sensor |
| 2 | + |
| 3 | +Push **Dagster run lifecycle events** (success + failure) as OTLP/HTTP log records to any OpenTelemetry-compatible backend — Splunk via Splunk OTel Collector, Datadog OTel ingest, Honeycomb, Sumo Logic OTel, Grafana Loki via OTel Collector, etc. |
| 4 | + |
| 5 | +Operational telemetry — distinct from the data-plane `dataframe_to_otlp_logs` sink. Parallels the existing `dagster_runs_to_prometheus_sensor` (Push Gateway / VM) and `dagster_runs_to_influxdb_sensor` — same `@run_status_sensor` pair (SUCCESS + FAILURE), different wire protocol. |
| 6 | + |
| 7 | +For failure-only OTLP shipment with richer error context, see `dagster_failures_to_otlp_sensor` — both can run side-by-side. |
| 8 | + |
| 9 | +## What lands at the backend per run-status event |
| 10 | + |
| 11 | +One OTLP `LogRecord` per run completion: |
| 12 | + |
| 13 | +| Field | Value | |
| 14 | +|---|---| |
| 15 | +| `body.stringValue` | `"Dagster run <run_id> for job <job_name> success (Xs)"` (or `failure step=… err=…`) | |
| 16 | +| `severityNumber` | 9 (INFO) for success, 17 (ERROR) for failure | |
| 17 | +| `severityText` | `INFO` / `ERROR` | |
| 18 | +| `timeUnixNano` | run end_time | |
| 19 | +| `attributes.dagster.run_id` | run UUID | |
| 20 | +| `attributes.dagster.job_name` | job name | |
| 21 | +| `attributes.dagster.status` | `success` / `failure` | |
| 22 | +| `attributes.dagster.duration_seconds` | double — wall-clock run time | |
| 23 | +| `attributes.dagster.failure_step` | step_key (failure only) | |
| 24 | +| `resource.service.name` | `dagster` | |
| 25 | +| `resource.service.instance.id` | `location_label` (deployment / region) | |
| 26 | + |
| 27 | +[//]: # (FIELDS:START - auto-generated by tools/regen_readme_fields.py) |
| 28 | + |
| 29 | +## Fields |
| 30 | + |
| 31 | +### Required |
| 32 | + |
| 33 | +| Field | Type | Description | |
| 34 | +|---|---|---| |
| 35 | +| `sensor_name` | `str` | Dagster sensor name. | |
| 36 | +| `otlp_endpoint_env_var` | `str` | Env var with OTLP/HTTP endpoint base URL (e.g. https://api.honeycomb.io). The /v1/logs path is appended. | |
| 37 | + |
| 38 | +### Sensor configuration |
| 39 | + |
| 40 | +| Field | Type | Default | Description | |
| 41 | +|---|---|---|---| |
| 42 | +| `default_status` | `str` | `"STOPPED"` | STOPPED \| RUNNING | |
| 43 | + |
| 44 | +### Other |
| 45 | + |
| 46 | +| Field | Type | Default | Description | |
| 47 | +|---|---|---|---| |
| 48 | +| `otlp_headers_env_var` | `str` | — | Env var with comma-separated HTTP headers (OTel convention: `x-honeycomb-team=<key>,x-honeycomb-dataset=dagster`). | |
| 49 | +| `service_name` | `str` | `"dagster"` | OTLP resource attribute `service.name`. | |
| 50 | +| `location_label` | `str` | `"default"` | OTLP resource attribute `service.instance.id` — usually deployment / region. | |
| 51 | +| `monitor_jobs` | `List[str]` | — | If set, only emit for these Dagster job names. None = all. | |
| 52 | +| `request_timeout_seconds` | `int` | `15` | — | |
| 53 | + |
| 54 | +[//]: # (FIELDS:END) |
| 55 | + |
| 56 | +## Example — Honeycomb |
| 57 | + |
| 58 | +```yaml |
| 59 | +type: dagster_community_components.DagsterRunsToOtlpSensorComponent |
| 60 | +attributes: |
| 61 | + sensor_name: dagster_runs_to_honeycomb |
| 62 | + otlp_endpoint_env_var: HONEYCOMB_OTLP_ENDPOINT |
| 63 | + otlp_headers_env_var: HONEYCOMB_OTLP_HEADERS |
| 64 | + service_name: dagster |
| 65 | + location_label: prod-east |
| 66 | +``` |
| 67 | +
|
| 68 | +Required env: |
| 69 | +
|
| 70 | +``` |
| 71 | +HONEYCOMB_OTLP_ENDPOINT=https://api.honeycomb.io |
| 72 | +HONEYCOMB_OTLP_HEADERS=x-honeycomb-team=<api_key>,x-honeycomb-dataset=dagster_runs |
| 73 | +``` |
| 74 | + |
| 75 | +## Example — Datadog OTel ingest |
| 76 | + |
| 77 | +```yaml |
| 78 | +type: dagster_community_components.DagsterRunsToOtlpSensorComponent |
| 79 | +attributes: |
| 80 | + sensor_name: dagster_runs_to_datadog |
| 81 | + otlp_endpoint_env_var: DD_OTLP_ENDPOINT |
| 82 | + otlp_headers_env_var: DD_OTLP_HEADERS |
| 83 | + service_name: dagster |
| 84 | +``` |
| 85 | +
|
| 86 | +Required env: |
| 87 | +
|
| 88 | +``` |
| 89 | +DD_OTLP_ENDPOINT=https://otlp-intake.logs.datadoghq.com |
| 90 | +DD_OTLP_HEADERS=DD-API-KEY=<api_key> |
| 91 | +``` |
| 92 | + |
| 93 | +## Example — Splunk via Splunk OTel Collector |
| 94 | + |
| 95 | +```yaml |
| 96 | +type: dagster_community_components.DagsterRunsToOtlpSensorComponent |
| 97 | +attributes: |
| 98 | + sensor_name: dagster_runs_to_splunk_otc |
| 99 | + otlp_endpoint_env_var: SPLUNK_OTC_ENDPOINT |
| 100 | + service_name: dagster |
| 101 | +``` |
| 102 | +
|
| 103 | +Required env: |
| 104 | +
|
| 105 | +``` |
| 106 | +SPLUNK_OTC_ENDPOINT=http://splunk-otc.svc:4318 |
| 107 | +``` |
| 108 | + |
| 109 | +For Splunk HEC direct (no OTel Collector), use `dagster_runs_to_splunk_hec_sensor` — same shape, native HEC payload. |
| 110 | + |
| 111 | +## Why two sensors (SUCCESS + FAILURE)? |
| 112 | + |
| 113 | +Dagster's `@run_status_sensor` decorator filters on a single `run_status`. The component wires up two — one for SUCCESS, one for FAILURE — so both event types push their own LogRecord with the right `severityNumber` (9 vs 17) and `dagster.status` attribute. |
| 114 | + |
| 115 | +## Relationship to other telemetry sensors |
| 116 | + |
| 117 | +| Sensor | Scope | Wire | |
| 118 | +|---|---|---| |
| 119 | +| **`dagster_runs_to_otlp_sensor`** (this one) | success + failure | OTLP/HTTP | |
| 120 | +| `dagster_runs_to_prometheus_sensor` | success + failure | Prometheus Push Gateway / VM remote_write | |
| 121 | +| `dagster_runs_to_influxdb_sensor` | success + failure | InfluxDB line protocol | |
| 122 | +| `dagster_runs_to_splunk_hec_sensor` | success + failure | Splunk HEC direct | |
| 123 | +| `dagster_failures_to_otlp_sensor` | failure only (richer error context) | OTLP/HTTP | |
| 124 | +| `dagster_materializations_to_prometheus_sensor` | asset materialization events | Prometheus Push Gateway / VM | |
| 125 | + |
| 126 | +Use whichever combination matches your observability stack. They're independent and can run side-by-side. |
| 127 | + |
| 128 | +## See also |
| 129 | + |
| 130 | +- [OTLP/HTTP logs spec](https://opentelemetry.io/docs/specs/otlp/#otlphttp-logs-binary-protocol) |
| 131 | +- `dataframe_to_otlp_logs` (in `assets/sinks/`) — **distinct** — data-plane DataFrame sink, not run events |
| 132 | +- `compute_log_managers/otlp/` — **distinct** — instance-level CLM shipping op stdout/stderr (not run events) |
0 commit comments