# client

Python API: `luxonis_ml.telemetry.client`

## Classes

| Name | Description |
| --- | --- |
|
[`Telemetry`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Telemetry client for emitting events via pluggable backends. |

### class `Telemetry`

```python
class Telemetry
```

Telemetry client for emitting events via pluggable backends.

Properties

| Name | Type | Description |
| --- | --- | --- |
|
[`config`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| `TelemetryConfig` | |
|
[`is_enabled`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| `bool` | |
|
[`library_name`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| `str` | |
|
[`library_version`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| `str | None` | |
|
[`source_component`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| `str` | |

Methods

| Name | Description |
| --- | --- |
|
[`__init__`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Initialize a telemetry client. |
|
[`add_context_provider`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Register a context provider for all events. |
|
[`add_system_context_provider`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Register a context provider used only with system metadata. |
|
[`capture`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Capture a telemetry event. |
|
[`extend_context_providers`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Register multiple context providers. |
|
[`extend_system_context_providers`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Register multiple system context providers. |
|
[`flush`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Flush any buffered telemetry events. |
|
[`register_backend`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Register a custom backend class. |
|
[`shutdown`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| Shutdown the backend and flush pending telemetry. |

#### property `config`

```python
config: TelemetryConfig
```

#### property `is_enabled`

```python
is_enabled: bool
```

#### property `library_name`

```python
library_name: str
```

#### property `library_version`

```python
library_version: str | None
```

#### property `source_component`

```python
source_component: str
```

#### method `__init__`

```python
def __init__(
    library_name: str,
    *,
    source_component: str | None = None,
    library_version: str | None = None,
    config: TelemetryConfig | None = None,
    context_providers: list[ContextProvider] | None = None,
    system_context_providers: list[SystemContextProvider] | None = None,
)
```

Initialize a telemetry client.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `library_name` | `str` | Name of the library emitting telemetry, such as `"luxonis_ml"`. | required |
| `source_component` | `str | None` | Optional emitter/component name for the event context. If omitted, the library name is
reused. | `None` |
| `library_version` | `str | None` | Version string for the library. If omitted, it is resolved from package metadata when
possible. | `None` |
| `config` | `TelemetryConfig | None` | Telemetry configuration to use. If omitted, values are read from environment variables. |
`None` |
| `context_providers` | `list[ContextProvider] | None` | Callables that return extra context to attach to every event. | `None` |
| `system_context_providers` | `list[SystemContextProvider] | None` | Callables that return extra context to attach only when
system metadata is requested. | `None` |

#### method `add_context_provider`

```python
def add_context_provider(provider: ContextProvider)
```

Register a context provider for all events.

#### method `add_system_context_provider`

```python
def add_system_context_provider(provider: SystemContextProvider)
```

Register a context provider used only with system metadata.

#### method `capture`

```python
def capture(
    event: str,
    properties: dict[str, Any] | None = None,
    *,
    allowlist: set[str] | None = None,
    include_system_metadata: bool | None = None,
    distinct_id: str | None = None,
)
```

Capture a telemetry event.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `event` | `str` | Event name, such as `"train_started"`. | required |
| `properties` | `dict[str, Any] | None` | Optional event properties. Values are sanitized and redacted before sending. | `None` |
| `allowlist` | `set[str] | None` | If set, only these property keys are included. | `None` |
| `include_system_metadata` | `bool | None` | Whether to add extended system metadata for this event. If omitted, the config
default is used. | `None` |
| `distinct_id` | `str | None` | Optional backend identity override. When omitted, it defaults to the client's ephemeral session
identifier. | `None` |

#### method `extend_context_providers`

```python
def extend_context_providers(providers: list[ContextProvider] | None)
```

Register multiple context providers.

#### method `extend_system_context_providers`

```python
def extend_system_context_providers(providers: list[SystemContextProvider] | None)
```

Register multiple system context providers.

#### method `flush`

```python
def flush()
```

Flush any buffered telemetry events.

#### class method `register_backend`

```python
def register_backend(name: str, backend_cls: type[TelemetryBackend])
```

Register a custom backend class.

> **Example**
> Register a backend and select it through the config.

```python
Telemetry.register_backend("my_backend", MyBackend)

config = TelemetryConfig(backend="my_backend")
telemetry = Telemetry("luxonis_ml", config=config)
```

> **Note**
> Registration replaces any backend already stored under the same name.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Backend name used in `TelemetryConfig.backend`. The name is stored in lower case, so the lookup ignores case. |
required |
| `backend_cls` | `type[TelemetryBackend]` | Backend class instantiated with `TelemetryConfig`. | required |

#### method `shutdown`

```python
def shutdown()
```

Shutdown the backend and flush pending telemetry.

## Module Attributes

| Name | Description |
| --- | --- |
|
[`ContextProvider`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| |
|
[`SystemContextProvider`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
| |

### type alias `ContextProvider`

```python
ContextProvider = Callable[[Telemetry], dict[str, Any]]
```

### type alias `SystemContextProvider`

```python
SystemContextProvider = Callable[[Telemetry], dict[str, Any]]
```
