> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability moved into @iii-dev/helpers as a submodule

> The iii-observability package (Node, Python, Rust) merges into the helpers package as a new observability submodule. The standalone iii-observability packages become deprecated shims.

## What changed

The observability surface (`Logger`, `initOtel` / `init_otel`, `withSpan` / `with_span`, `executeTracedRequest` / `execute_traced_request`, and the rest of the public API) moves from the standalone `iii-observability` packages into the **`@iii-dev/helpers`** package as a new `observability` submodule.

| Submodule     | Node                             | Python                      | Rust                         |
| ------------- | -------------------------------- | --------------------------- | ---------------------------- |
| observability | `@iii-dev/helpers/observability` | `iii_helpers.observability` | `iii_helpers::observability` |

Node also exposes an internal-only entry point `@iii-dev/helpers/observability/internal` that provides `getMeter` and `getTracer`. This entry point is not part of the public API; it is reserved for first-party iii packages.

### OpenTelemetry dependencies

The OpenTelemetry dependencies are now bundled in `@iii-dev/helpers` / `iii-helpers` directly. For SDK users this is net-neutral: the root SDK already depended on `iii-observability`, which pulled in otel. The dependency now flows through the helpers package instead.

### Deprecated shims

The standalone packages remain published but are deprecated. They re-export the public API from the helpers `observability` submodule. Importing from the old packages continues to work but emits a deprecation signal:

| Language | Deprecated package              | Deprecation mechanism                  |
| -------- | ------------------------------- | -------------------------------------- |
| Node     | `@iii-dev/observability`        | `@deprecated` JSDoc on every re-export |
| Python   | `iii-observability` (PyPI)      | `DeprecationWarning` at import time    |
| Rust     | `iii-observability` (crates.io) | `#![deprecated]` crate-level attribute |

The shim covers the public API only. Node's internal-only `getMeter` and `getTracer` symbols are not re-exported by the shim and now live at `@iii-dev/helpers/observability/internal` (previously `@iii-dev/observability/internal` before the migration).

## Migration

Replace imports of the standalone `iii-observability` packages with the `observability` submodule path from helpers.

Node:

```ts theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
// Before
import { Logger, initOtel, withSpan } from '@iii-dev/observability'
// After
import { Logger, initOtel, withSpan } from '@iii-dev/helpers/observability'
```

Python:

```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
# Before
from iii_observability import Logger, init_otel, with_span
# After
from iii_helpers.observability import Logger, init_otel, with_span
```

Rust:

```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
// Before
use iii_observability::{Logger, init_otel, with_span};
// After
use iii_helpers::observability::{Logger, init_otel, with_span};
```