id_effect 0.4.0

Effect<A, E, R> (sync + async), capability DI, pipe — interpreter-style, no bundled executor
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# OpenTelemetry (`id_effect_opentelemetry`)

The workspace crate **`id_effect_opentelemetry`** implements **Phase B** of the Effect.ts parity plan:
first-class **OpenTelemetry** traces and metrics alongside `id_effect`’s fiber-local
[`with_span`](https://docs.rs/id_effect/latest/id_effect/fn.with_span.html) and
[`Metric`](https://docs.rs/id_effect/latest/id_effect/struct.Metric.html) primitives.

Design goals match [`@effect/opentelemetry`](https://www.npmjs.com/package/@effect/opentelemetry):

- **Opt-in at the dependency boundary** — the core `id_effect` crate does not depend on OTEL.
- **Tracing** — bridge `tracing` spans to OTEL exporters (OTLP in production; in-memory in tests).
- **Propagation** — W3C Trace Context (`traceparent` / `tracestate`) on portable header maps.
- **Metrics** — dual-write bridges from `Metric` counters and duration histograms to OTEL instruments.

## Tracing: compose `with_span` and OTEL

Use [`id_effect_opentelemetry::with_span_otel`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.with_span_otel.html)
when you want **both**:

1. Fiber-local span stack and `EffectEvent` stream (`id_effect::with_span`), and
2. A `tracing` span exported through [`tracing_opentelemetry`](https://docs.rs/tracing-opentelemetry).

Build a tracer provider (here: in-memory for tests), install a `tracing` subscriber with an OTEL layer,
then run effects under `with_span_otel`:

```rust
use id_effect::{install_tracing_layer, run_blocking, succeed, TracingConfig};
use id_effect_opentelemetry::{
  sdk_tracer_provider_with_in_memory_exporter, trace_subscriber_for_provider, with_span_otel,
};
use opentelemetry_sdk::trace::InMemorySpanExporter;

let exporter = InMemorySpanExporter::default();
let provider = sdk_tracer_provider_with_in_memory_exporter(&exporter);
let subscriber = trace_subscriber_for_provider(&provider, false, None);

tracing::subscriber::with_default(subscriber, || {
  let _ = run_blocking(install_tracing_layer(TracingConfig::enabled()), ());
  let eff = with_span_otel("request", succeed::<(), (), ()>(()));
  let _ = run_blocking(eff, ());
});

let _ = provider.force_flush();
# let _ = provider.shutdown();
```

In production you typically:

1. Configure an OTLP exporter (or another `SpanExporter`) on [`SdkTracerProvider`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/trace/struct.SdkTracerProvider.html).
2. Call [`register_global_tracer_provider`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.register_global_tracer_provider.html) once at startup.
3. Install a global [`tracing_subscriber`](https://docs.rs/tracing-subscriber) stack with
   [`tracing_opentelemetry::layer()`](https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/fn.layer.html).

## W3C Trace Context on header maps

For HTTP clients built on `Vec<(String, String)>` (or similar), use:

- [`install_w3c_trace_context_propagator`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.install_w3c_trace_context_propagator.html) once per process.
- [`inject_trace_context_into_headers`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.inject_trace_context_into_headers.html) before sending a downstream request.
- [`extract_trace_context_from_headers`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.extract_trace_context_from_headers.html) when handling an incoming request.

For Axum / `http::HeaderMap`, map headers into this shape at the boundary or add a small adapter in your app.

## Metrics: `CounterBridge` and `DurationHistogramBridge`

[`CounterBridge`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.CounterBridge.html) and
[`DurationHistogramBridge`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.DurationHistogramBridge.html)
keep `id_effect::Metric` snapshots for tests while exporting measurements to OTEL.

Create an [`SdkMeterProvider`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/metrics/struct.SdkMeterProvider.html)
with a [`PeriodicReader`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/metrics/struct.PeriodicReader.html)
and an [`InMemoryMetricExporter`](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/metrics/struct.InMemoryMetricExporter.html)
for CI-style assertions, or wire an OTLP metrics exporter for production.

**Cardinality:** keep label sets small and stable; prefer bounded `service`, `route`, `tenant` keys over
high-cardinality user IDs in metric attributes.

## Axum + Tokio production sketch

1. Build tracer + meter providers with OTLP endpoints from `id_effect_config` (or env).
2. Register globals and `try_init` a `tracing_subscriber` registry (fmt + OTEL + optional `EnvFilter`).
3. In Axum middleware, extract `traceparent` into an OTEL [`Context`](https://docs.rs/opentelemetry/latest/opentelemetry/struct.Context.html),
   attach it to the request extension, and spawn handler work inside that context.
4. On graceful shutdown, call `force_flush` / `shutdown` on providers (mirror `Scope` finalizer patterns from `id_effect`).

See also: `docs/effect-ts-parity/phases/phase-b-opentelemetry.md` in the repository for the full task breakdown and Beads slug map.


## Production OTLP

Enable the default `otlp` feature (or pass `--features otlp` explicitly). At process start:

```rust
use id_effect_opentelemetry::{OtelConfig, install_from_config, graceful_otel_shutdown};

let guard = install_from_config(OtelConfig::from_env()?)?;
// register Axum routes, run effects, etc.
guard.force_flush();
graceful_otel_shutdown(guard);
```

[`OtelStarterGuard`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.OtelStarterGuard.html) exposes
[`meter()`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.OtelStarterGuard.html#method.meter),
[`force_flush`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.OtelStarterGuard.html#method.force_flush),
and [`shutdown`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.OtelStarterGuard.html#method.shutdown).

### Capability DI

Register the runtime handle for programs that need flush/shutdown in domain code:

```rust
use std::sync::Arc;
use id_effect_opentelemetry::{provide_otel_runtime, OtelRuntime};

let guard = Arc::new(install_from_config(OtelConfig::from_env()?)?);
let provider = provide_otel_runtime(guard);
// env.insert via provider.build(...)
```

### Graceful shutdown (Tokio)

```rust
use id_effect_opentelemetry::shutdown_otel_on_signal;

shutdown_otel_on_signal(guard).await;
```

### Logs

[`install_otel_starter`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.install_otel_starter.html) installs a
`tracing_subscriber` stack with both OTEL trace and log export layers. Use structured
`tracing::info!(target: "id_effect_opentelemetry", ...)` events or wire
[`OtelLogBackend`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/struct.OtelLogBackend.html) into
[`id_effect_logger`](https://docs.rs/id_effect_logger).

### `id_effect_config` keys (`config` feature)

| Key | Maps to |
|-----|---------|
| `otel.endpoint` | OTLP endpoint |
| `otel.protocol` | `grpc` or `http` |
| `otel.service_name` | `service.name` |
| `otel.service_version` | `service.version` |
| `otel.headers` | OTLP request headers |

Use [`load_otel_config`](https://docs.rs/id_effect_opentelemetry/latest/id_effect_opentelemetry/fn.load_otel_config.html) when a
[`ConfigProvider`](https://docs.rs/id_effect_config) is already available.