telemetry
最后更新
luxonis_ml.telemetryLuxonis 包的公共遥测 API。luxonis_ml.telemetry 包公开了一个轻量级事件捕获客户端、环境驱动配置、单例助手、上下文提供程序和抑制工具。它旨在让消费包可以发出使用事件,而无需直接耦合到特定的分析后端。PostHog 支持通过 luxonis-ml[telemetry] 可选;禁用、配置错误和调试配置可以使用无操作或标准输出后端。示例
从组件发出事件,同时保持后端配置与调用站点分离。
Python
1from luxonis_ml.telemetry import Telemetry
2
3telemetry = Telemetry("luxonis_ml", source_component="data")
4telemetry.capture(
5 "dataset_export_started",
6 {"dataset_type": "coco"},
7)注意
遥测故障对于主机应用程序来说故意是非致命的。无法初始化的后端会回退到 NoopBackend,并且失败的捕获、刷新或关闭会被抑制而不是引发。
配置
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 仪器
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"})cyclopts.App。另请参阅
luxonis_ml.telemetry.cli 用于排除的回调、
exclude_commands 参数和 skip_telemetry 装饰器。自定义后端
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)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)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])单例用法
(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")。环境变量
LUXONIS_TELEMETRY_ENABLED:启用遥测。默认情况下启用。设置一个假值以关闭遥测。LUXONIS_TELEMETRY_BACKEND:后端名称,例如posthog、stdout或自定义注册名称。LUXONIS_TELEMETRY_API_KEY:后端的 API 密钥。LUXONIS_TELEMETRY_ENDPOINT:后端主机 URL。LUXONIS_TELEMETRY_DEBUG:当为真时,后端回退到stdout而不是posthog。
LUXONIS_TELEMETRY_IS_LUXONIS_CLOUD。它标记 Luxonis 云作业发出的事件。要关闭一个代码块的遥测,请使用 suppress_telemetry。另请参阅
luxonis_ml.telemetry.client 用于捕获客户端,luxonis_ml.telemetry.config 用于配置,luxonis_ml.telemetry.context 用于每个事件携带的精确上下文键,luxonis_ml.telemetry.cli 用于命令行仪器,以及 luxonis_ml.telemetry.backends 用于后端实现。