此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 配置
  • CLI 仪器
  • 自定义后端
  • 上下文和元数据
  • 单例用法
  • 环境变量
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.telemetryLuxonis 包的公共遥测 API。luxonis_ml.telemetry 包公开了一个轻量级事件捕获客户端、环境驱动配置、单例助手、上下文提供程序和抑制工具。它旨在让消费包可以发出使用事件,而无需直接耦合到特定的分析后端。PostHog 支持通过 luxonis-ml[telemetry] 可选;禁用、配置错误和调试配置可以使用无操作或标准输出后端。目录

配置

Telemetry 在您不传递配置时读取环境。传递 TelemetryConfig 以从调用站点控制后端:
Python
1from luxonis_ml.telemetry import Telemetry, TelemetryConfig
2
3config = TelemetryConfig(
4    enabled=True,
5    backend="posthog",
6    api_key="phc_xxx",
7    endpoint="https://us.i.posthog.com",
8)
9
10telemetry = Telemetry("luxonis_ml", config=config)
11telemetry.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 和 TelemetryDefaults 进行基于环境的配置,以保留特定于库的回退:
Python
1from luxonis_ml.telemetry import TelemetryConfig, TelemetryDefaults
2
3config = TelemetryConfig.from_environ(
4    defaults=TelemetryDefaults(
5        backend="stdout",
6        include_system_metadata=True,
7    )
8)
当一个库从多个表面发出事件并且这些发射器需要单独的基本上下文时,提供 source_component:
Python
1from luxonis_ml.telemetry import Telemetry
2
3data_telemetry = Telemetry("luxonis_ml", source_component="data")
4archive_telemetry = Telemetry("luxonis_ml", source_component="nn_archive")

CLI 仪器

instrument_typer 和 instrument_cyclopts 包装应用程序的命令。每个被检测的命令都会发出一个 cli_command 事件:
Python
1import typer
2
3from luxonis_ml.telemetry import Telemetry
4from luxonis_ml.telemetry.cli import instrument_typer
5
6app = typer.Typer()
7telemetry = Telemetry("luxonis_ml")
8
9instrument_typer(app, telemetry)
事件包含命令名称、成功标志和持续时间。参数值保持本地。命名您允许离开机器的参数,然后一个允许列表涵盖应用程序的每个命令:
Python
1instrument_typer(app, telemetry, allowlist={"name"})
instrument_cyclopts 接受相同的参数并以相同的方式包装 cyclopts.App。

自定义后端

该包附带 PostHogBackend、StdoutBackend 和 NoopBackend。对于其他任何情况,请子类化 TelemetryBackend,注册该类,然后按名称选择它:
Python
1from luxonis_ml.telemetry import Telemetry, TelemetryConfig
2from luxonis_ml.telemetry.backends.base import TelemetryBackend
3
4
5class MyBackend(TelemetryBackend):
6    def capture(self, event):
7        print("event", event)
8
9
10Telemetry.register_backend("my_backend", MyBackend)
11
12config = TelemetryConfig(enabled=True, backend="my_backend")
13telemetry = Telemetry("luxonis_ml", config=config)
14telemetry.capture("custom_event")
后端名称不区分大小写,因此 "My_Backend" 和 "my_backend" 解析为同一个后端。

上下文和元数据

每个事件都带有一个基本上下文,其中包含 $process_person_profile、$session_id、source_product、source_component 和 sdk_version。$session_id 值在 Telemetry 实例的生命周期内保持不变。PostHog 后端也将其用作默认的 distinct_id,您可以为单个事件覆盖它:
Python
1from luxonis_ml.telemetry import Telemetry
2
3telemetry = Telemetry("luxonis_ml")
4
5telemetry.capture("dataset_info_requested", {"name": "beans"})
6telemetry.capture(
7    "dataset_export_finished",
8    {"format": "coco"},
9    distinct_id="export-run-123",
10)
system_context_provider 添加主机和运行时字段 os、os_version、arch、python_version、ci、is_luxonis_cloud、processor、cpu_count 和 is_docker。使用 host_context_provider 仅用于粗略的主机字段:
Python
1from luxonis_ml.telemetry import Telemetry, system_context_provider
2
3telemetry = Telemetry(
4    "luxonis_ml",
5    system_context_providers=[system_context_provider],
6)
7
8telemetry.capture("dataset_export_finished", include_system_metadata=True)
host_context 和 system_context 直接返回相同的值。自定义提供程序将您自己的字段添加到每个事件:
Python
1from luxonis_ml.telemetry import Telemetry
2
3
4def dataset_context(_telemetry):
5    return {"dataset_plugin": "internal"}
6
7
8telemetry = Telemetry("luxonis_ml", context_providers=[dataset_context])

单例用法

get_or_init 和 get_telemetry 为每个 (library_name, source_component) 对保留一个实例:
Python
1from luxonis_ml.telemetry import get_or_init
2
3telemetry = get_or_init("luxonis_ml")
4telemetry.capture("dataset_ls_invoked")
单独初始化库的每个组件:
Python
1from luxonis_ml.telemetry import get_or_init, get_telemetry
2
3get_or_init("luxonis_ml", source_component="data")
4get_or_init("luxonis_ml", source_component="nn_archive")
5
6data_telemetry = get_telemetry("luxonis_ml", source_component="data")
7archive_telemetry = get_telemetry(
8    "luxonis_ml", source_component="nn_archive"
9)
如果您省略 source_component,则首先运行查找并返回已为库注册的实例,无论其组件是什么。然后新实例使用库名称作为组件。对同一对的第二次 get_or_init 调用会重用该实例。它会忽略不同的 config 或 library_version 并发出警告,并将新的上下文提供程序合并到实例中。get_telemetry 对于模糊查找返回 None,例如在 data 和 nn_archive 都已注册时调用 get_telemetry("luxonis_ml")。

环境变量

该包读取这些变量。TelemetryConfig.from_environ 首先解析它们,然后是 TelemetryDefaults 的值,然后是基本 TelemetryConfig 默认值。
  • 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 读取另一个变量 LUXONIS_TELEMETRY_IS_LUXONIS_CLOUD。它标记 Luxonis 云作业发出的事件。要关闭一个代码块的遥测,请使用 suppress_telemetry。

子页面