fix(telemetry): address review comments

- Set the global OTEL error handler only when telemetry is enabled
- Correct finishTelemetry doc comment (handles are nil only when uninitialized)
- Restore the previous tracer provider in gitops/actions attribute tests
- Document the telemetry config block in docs/config.md

Author: LauJosefsen

actions/telemetry_test.go

@@ -12,8 +12,12 @@ import (
 func TestSetActionAttrs(t *testing.T) {
 	exp := tracetest.NewInMemoryExporter()
 	tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exp))
+	prev := otel.GetTracerProvider()
 	otel.SetTracerProvider(tp)
-	t.Cleanup(func() { _ = tp.Shutdown(context.Background()) })
+	t.Cleanup(func() {
+		otel.SetTracerProvider(prev)
+		_ = tp.Shutdown(context.Background())
+	})
 
 	_, span := tp.Tracer("test").Start(context.Background(), "action.run")
 	setActionAttrs(span, "proj:up:default", "proj", "docker compose up")

cmd/root.go

@@ -99,7 +99,8 @@ func Execute() {
 }
 
 // finishTelemetry records the final command status on the root span and flushes
-// pending spans. Safe to call when telemetry is disabled (handles are nil).
+// pending spans. Safe to call when telemetry was never initialized (e.g.
+// completion commands or an early config failure), where the handles remain nil.
 func finishTelemetry(err error) {
 	if globalRootSpan != nil {
 		if err != nil {

docs/config.md

@@ -18,6 +18,7 @@ An optional `.gitte-override.yml` in the same directory is deep-merged on top, u
 - [searchFor](#searchfor)
 - [feature\_gates](#feature_gates)
 - [sources](#sources)
+- [telemetry](#telemetry)
 - [Remote configuration](#remote-configuration)
 
 ---
@@ -34,6 +35,7 @@ sources:        # auto-discovery sources (optional)
 searchFor:      # global output pattern matching (optional)
 actionOverride: # per-action overrides (optional)
 retry:          # global retry defaults (optional)
+telemetry:      # OpenTelemetry trace export (optional)
 ```
 
 ---
@@ -397,6 +399,38 @@ gitte run up --discover    # discover, then sync, then run actions
 
 ---
 
+## telemetry
+
+Gitte can export OpenTelemetry traces over OTLP/HTTP to an OTLP-compatible backend (e.g. Elastic APM) to help debug failures. Telemetry is enabled whenever an endpoint is resolved.
+
+```yaml
+telemetry:
+  endpoint: https://apm.example.com:8200   # OTLP/HTTP endpoint
+  headers:                                  # arbitrary export headers (optional)
+    Authorization: "Bearer <secret-token>"  # or: "ApiKey <base64-key>"
+```
+
+| Field | Description |
+|-------|-------------|
+| `endpoint` | OTLP/HTTP endpoint to export spans to. Telemetry is enabled when this resolves to a non-empty value. |
+| `headers` | Map of HTTP headers attached to every export request — typically authentication (`Authorization`). |
+
+Each invocation produces one trace: a root span for the command, child spans for each repo sync (branch, commit SHA, dirty flag) and each action task (command, exit code), with errors recorded on the relevant span. The OS username (`user.name`) and hostname (`host.name`) are attached to every trace to identify which developer and machine produced it.
+
+The gitte CLI arguments and each action's command line are exported as span attributes. Keep secrets out of action command definitions and CLI arguments — pass them via environment variables, which are not exported. Full remote URLs are never collected (repos are identified by name only).
+
+Environment variables override or disable telemetry:
+
+| Variable | Effect |
+|----------|--------|
+| `GITTE_TELEMETRY=off` | Disable telemetry locally (kill-switch) |
+| `GITTE_TELEMETRY_URL` | Override the endpoint |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | Standard OTEL env vars, honored as a fallback when no gitte endpoint is set |
+
+Precedence: `GITTE_TELEMETRY=off` > `GITTE_TELEMETRY_URL` > config `endpoint` > `OTEL_EXPORTER_OTLP_*`. Telemetry is best-effort and never blocks or slows gitte; export failures are silently ignored and flushing on exit is time-bounded.
+
+---
+
 ## Remote configuration
 
 Gitte can load its configuration from a remote git repository. Create a `.gitte-env` file alongside `.gitte.yml`:

gitops/telemetry_test.go

@@ -12,8 +12,12 @@ import (
 func TestSetGitContextAttrs(t *testing.T) {
 	exp := tracetest.NewInMemoryExporter()
 	tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exp))
+	prev := otel.GetTracerProvider()
 	otel.SetTracerProvider(tp)
-	t.Cleanup(func() { _ = tp.Shutdown(context.Background()) })
+	t.Cleanup(func() {
+		otel.SetTracerProvider(prev)
+		_ = tp.Shutdown(context.Background())
+	})
 
 	_, span := tp.Tracer("test").Start(context.Background(), "gitops.sync")
 	setGitContextAttrs(span, "main", "abc123", true)

telemetry/telemetry.go

@@ -100,13 +100,14 @@ func resourceAttributes(version, username, hostname string) []attribute.KeyValue
 // always non-nil and safe to call; setup failures and disabled telemetry both
 // degrade to a no-op shutdown.
 func Init(ctx context.Context, cfg *config.GitteConfig, version string) func() {
-	otel.SetErrorHandler(noopErrorHandler{})
-
 	r := Resolve(cfg)
 	if !r.Enabled {
 		return func() {}
 	}
 
+	// Only mutate process-wide OTEL state once telemetry is known to be enabled.
+	otel.SetErrorHandler(noopErrorHandler{})
+
 	var opts []otlptracehttp.Option
 	if !r.UseSDKEnv {
 		opts = append(opts, otlptracehttp.WithEndpointURL(r.Endpoint))