# telemetry

Python API: `luxonis_ml.telemetry`

Luxonis 包的公共遥测 API。

`luxonis_ml.telemetry` 包公开了一个轻量级事件捕获客户端、环境驱动配置、单例助手、上下文提供程序和抑制工具。它旨在让消费包可以发出使用事件，而无需直接耦合到特定的分析后端。PostHog 支持通过
`luxonis-ml[telemetry]` 可选；禁用、配置错误和调试配置可以使用无操作或标准输出后端。

> **示例**
> 从组件发出事件，同时保持后端配置与调用站点分离。

```python
from luxonis_ml.telemetry import Telemetry

telemetry = Telemetry("luxonis_ml", source_component="data")
telemetry.capture(
    "dataset_export_started",
    {"dataset_type": "coco"},
)
```

> **注意**
> 遥测故障对于主机应用程序来说故意是非致命的。无法初始化的后端会回退到 [NoopBackend](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends/noop.md)，并且失败的捕获、刷新或关闭会被抑制而不是引发。

目录

 * [配置](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)
 * [CLI
   仪器](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)
 * [自定义后端](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)
 * [上下文和元数据](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)
 * [单例用法](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)
 * [环境变量](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry.md)

## 配置

[Telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
在您不传递配置时读取环境。传递
[TelemetryConfig](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
以从调用站点控制后端：

```python
from luxonis_ml.telemetry import Telemetry, TelemetryConfig

config = TelemetryConfig(
    enabled=True,
    backend="posthog",
    api_key="phc_xxx",
    endpoint="https://us.i.posthog.com",
)

telemetry = Telemetry("luxonis_ml", config=config)
telemetry.capture("dataset_parse_started", {"dataset_format": "coco"})
```

有几个字段会改变离开机器的内容。`allowlist` 只保留您命名的属性键，它涵盖每个事件，而不仅仅是 CLI 事件。`include_system_metadata=True`
将系统上下文添加到每个事件。`include_base_context=False` 删除了共享的基本上下文，适用于构建自己的库。`disable_geoip=True` 阻止 PostHog 从 IP
地址派生粗略位置数据；默认情况下会保留该丰富功能。`allow_reserved_overrides=True` 允许调用者或上下文提供程序覆盖下面的基本上下文字段，否则这些字段受保护。

使用
[TelemetryConfig.from_environ](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
和
[TelemetryDefaults](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
进行基于环境的配置，以保留特定于库的回退：

```python
from luxonis_ml.telemetry import TelemetryConfig, TelemetryDefaults

config = TelemetryConfig.from_environ(
    defaults=TelemetryDefaults(
        backend="stdout",
        include_system_metadata=True,
    )
)
```

当一个库从多个表面发出事件并且这些发射器需要单独的基本上下文时，提供 `source_component`：

```python
from luxonis_ml.telemetry import Telemetry

data_telemetry = Telemetry("luxonis_ml", source_component="data")
archive_telemetry = Telemetry("luxonis_ml", source_component="nn_archive")
```

## CLI 仪器

[instrument_typer](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli/typer.md)
和
[instrument_cyclopts](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli/cyclopts.md)
包装应用程序的命令。每个被检测的命令都会发出一个 `cli_command` 事件：

```python
import typer

from luxonis_ml.telemetry import Telemetry
from luxonis_ml.telemetry.cli import instrument_typer

app = typer.Typer()
telemetry = Telemetry("luxonis_ml")

instrument_typer(app, telemetry)
```

事件包含命令名称、成功标志和持续时间。参数值保持本地。命名您允许离开机器的参数，然后一个允许列表涵盖应用程序的每个命令：

```python
instrument_typer(app, telemetry, allowlist={"name"})
```

[instrument_cyclopts](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli/cyclopts.md)
接受相同的参数并以相同的方式包装 `cyclopts.App`。

> **另请参阅**
> [luxonis_ml.telemetry.cli](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli.md) 用于排除的回调、`exclude_commands` 参数和 [skip_telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli/shared.md) 装饰器。

## 自定义后端

该包附带
[PostHogBackend](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends/posthog.md)、[StdoutBackend](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends/stdout.md)
和
[NoopBackend](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends/noop.md)。对于其他任何情况，请子类化
[TelemetryBackend](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends/base.md)，注册该类，然后按名称选择它：

```python
from luxonis_ml.telemetry import Telemetry, TelemetryConfig
from luxonis_ml.telemetry.backends.base import TelemetryBackend

class MyBackend(TelemetryBackend):
    def capture(self, event):
        print("event", event)

Telemetry.register_backend("my_backend", MyBackend)

config = TelemetryConfig(enabled=True, backend="my_backend")
telemetry = Telemetry("luxonis_ml", config=config)
telemetry.capture("custom_event")
```

后端名称不区分大小写，因此 `"My_Backend"` 和 `"my_backend"` 解析为同一个后端。

## 上下文和元数据

每个事件都带有一个基本上下文，其中包含 `$process_person_profile`、`$session_id`、`source_product`、`source_component` 和 `sdk_version`。`$session_id` 值在
[Telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
实例的生命周期内保持不变。PostHog 后端也将其用作默认的 `distinct_id`，您可以为单个事件覆盖它：

```python
from luxonis_ml.telemetry import Telemetry

telemetry = Telemetry("luxonis_ml")

telemetry.capture("dataset_info_requested", {"name": "beans"})
telemetry.capture(
    "dataset_export_finished",
    {"format": "coco"},
    distinct_id="export-run-123",
)
```

[system_context_provider](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
添加主机和运行时字段 `os`、`os_version`、`arch`、`python_version`、`ci`、`is_luxonis_cloud`、`processor`、`cpu_count` 和 `is_docker`。使用
[host_context_provider](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
仅用于粗略的主机字段：

```python
from luxonis_ml.telemetry import Telemetry, system_context_provider

telemetry = Telemetry(
    "luxonis_ml",
    system_context_providers=[system_context_provider],
)

telemetry.capture("dataset_export_finished", include_system_metadata=True)
```

[host_context](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
和
[system_context](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
直接返回相同的值。自定义提供程序将您自己的字段添加到每个事件：

```python
from luxonis_ml.telemetry import Telemetry

def dataset_context(_telemetry):
    return {"dataset_plugin": "internal"}

telemetry = Telemetry("luxonis_ml", context_providers=[dataset_context])
```

## 单例用法

[get_or_init](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/singleton.md)
和
[get_telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/singleton.md)
为每个 `(library_name, source_component)` 对保留一个实例：

```python
from luxonis_ml.telemetry import get_or_init

telemetry = get_or_init("luxonis_ml")
telemetry.capture("dataset_ls_invoked")
```

单独初始化库的每个组件：

```python
from luxonis_ml.telemetry import get_or_init, get_telemetry

get_or_init("luxonis_ml", source_component="data")
get_or_init("luxonis_ml", source_component="nn_archive")

data_telemetry = get_telemetry("luxonis_ml", source_component="data")
archive_telemetry = get_telemetry(
    "luxonis_ml", source_component="nn_archive"
)
```

如果您省略 `source_component`，则首先运行查找并返回已为库注册的实例，无论其组件是什么。然后新实例使用库名称作为组件。对同一对的第二次
[get_or_init](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/singleton.md)
调用会重用该实例。它会忽略不同的 `config` 或 `library_version`
并发出警告，并将新的上下文提供程序合并到实例中。[get_telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/singleton.md)
对于模糊查找返回 `None`，例如在 `data` 和 `nn_archive` 都已注册时调用 `get_telemetry("luxonis_ml")`。

## 环境变量

该包读取这些变量。[TelemetryConfig.from_environ](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
首先解析它们，然后是
[TelemetryDefaults](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
的值，然后是基本
[TelemetryConfig](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
默认值。

 * `LUXONIS_TELEMETRY_ENABLED`：启用遥测。默认情况下启用。设置一个假值以关闭遥测。
 * `LUXONIS_TELEMETRY_BACKEND`：后端名称，例如 `posthog`、`stdout` 或自定义注册名称。
 * `LUXONIS_TELEMETRY_API_KEY`：后端的 API 密钥。
 * `LUXONIS_TELEMETRY_ENDPOINT`：后端主机 URL。
 * `LUXONIS_TELEMETRY_DEBUG`：当为真时，后端回退到 `stdout` 而不是 `posthog`。

[luxonis_ml.telemetry.context](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
读取另一个变量 `LUXONIS_TELEMETRY_IS_LUXONIS_CLOUD`。它标记 Luxonis 云作业发出的事件。

要关闭一个代码块的遥测，请使用
[suppress_telemetry](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/suppression.md)。

> **另请参阅**
> [luxonis_ml.telemetry.client](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md) 用于捕获客户端，[luxonis_ml.telemetry.config](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md) 用于配置，[luxonis_ml.telemetry.context](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md) 用于每个事件携带的精确上下文键，[luxonis_ml.telemetry.cli](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli.md) 用于命令行仪器，以及 [luxonis_ml.telemetry.backends](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends.md) 用于后端实现。

## 子页面

 * [backends](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/backends.md)
 * [cli](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/cli.md)
 * [client](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/client.md)
 * [config](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/config.md)
 * [context](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/context.md)
 * [events](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/events.md)
 * [redaction](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/redaction.md)
 * [singleton](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/singleton.md)
 * [suppression](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/telemetry/suppression.md)
