# telemetry

Python API: `modelconverter.utils.telemetry`

modelconverter CLI 报告的遥测事件。

构建 CLI 通过 `luxonis_ml.telemetry` 为转换运行发送的属性负载：运行了哪个命令，如何配置转换，以及转换如何结束。报告的值是枚举值、布尔值、数字设置和从配置派生的分桶计数，而不是原始模型名称、路径或文件内容。通过环境变量传播的转换运行
ID 将主机端命令事件与转换 Docker 容器内部发出的事件关联起来。

## 类

### ArchiveOutputMode

转换后的模型交付形式。

可以是普通模型文件 (`native`) 或 Luxonis NN 存档 (`nn_archive`)。

#### 属性

##### NATIVE

##### NN_ARCHIVE

### CalibrationSource

为输入配置的校准数据类型。

#### 属性

##### IMAGE_DIRECTORY

##### RANDOM

##### REMOTE_LINK

### CommandName

发出命令遥测事件的 CLI 命令。

#### 属性

##### CONVERT

### CommandResult

命令或转换运行的结果。

#### 属性

##### FAILED

##### INTERRUPTED

##### SUCCESS

### ConfigSource

用于转换的配置来源。

#### 属性

##### ARCHIVE_DIRECTORY

##### DIRECT_MODEL_INPUT

##### NN_ARCHIVE

##### YAML_CONFIG

### ConversionPhase

转换结束时所处的转换阶段。

#### 属性

##### CONFIGURATION

##### CONVERSION

##### UPLOAD_INTERMEDIATE

##### UPLOAD_OUTPUT

### FailureReason

命令或转换运行未成功的原因。

#### 属性

##### CONFIG_ERROR

##### CONVERSION_ERROR

##### RUNTIME_ERROR

##### UPLOAD_ERROR

##### USER_INTERRUPT

### TelemetryFlowStep

流事件所属的转换生命周期步骤。

#### 属性

##### CONFIGURATION_RESOLVED

##### RESULT_RECORDED

## 函数

### bucket_count

```python
def bucket_count(value: int | None) -> str | None:
```

将计数减少为粗略的桶标签。

> **示例**
> ```pycon
>>> bucket_count(0)
'0'
>>> bucket_count(3)
'2_4'
>>> bucket_count(9)
'5_plus'
```

参数

 * `value` (`int | None`): 要报告的计数。分桶可防止遥测事件携带转换模型的精确形状。

返回

 * `str | None`: `"0"`、`"1"`、`"2_4"` 或 `"5_plus"` 之一，如果 `value` 为 `None`，则为 `None`。

### bucket_memory_bytes

```python
def bucket_memory_bytes(value: int | None) -> str | None:
```

将以字节为单位的内存大小减少为粗略的桶标签。

> **示例**
> ```pycon
>>> bucket_memory_bytes(256 * 1024**2)
'under_512m'
>>> bucket_memory_bytes(2 * 1024**3)
'1g_4g'
```

参数

 * `value` (`int | None`): 以字节为单位的内存大小，如
   [peak_ram_usage_bytes](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   所测量。

返回

 * `str | None`: `"under_512m"`、`"512m_1g"`、`"1g_4g"` 或 `"above_4g"` 之一，如果 `value` 为 `None`，则为 `None`。

### build_command_properties

```python
def build_command_properties(*, conversion_run_id: str, platform: Platform, runs_in_docker: bool, dev_image: bool, gpu_enabled: bool, tool_version: str | None, custom_image_provided: bool, memory_limit_set: bool, cpu_limit_set: bool, result: CommandResult, duration_ms: int, failure_reason: FailureReason | None = None) -> dict[str, ParamValue]:
```

构建命令遥测事件的属性。

参数

 * `conversion_run_id` (`str`): 将事件与转换运行关联的 ID。
 * `platform` (`Platform`): 命令调用的平台。
 * `runs_in_docker` (`bool`): 转换是否在 Docker 容器内运行。
 * `dev_image` (`bool`): 是否使用开发镜像标签。
 * `gpu_enabled` (`bool`): 是否请求了 GPU 访问。
 * `tool_version` (`str | None`): 平台的已解析工具版本，如果由自定义镜像标签决定，则为 `None`。
 * `custom_image_provided` (`bool`): 是否提供了自定义 Docker 镜像。镜像名称本身从不报告。
 * `memory_limit_set` (`bool`): 是否设置了内存限制。限制本身从不报告。
 * `cpu_limit_set` (`bool`): 是否设置了 CPU 限制。限制本身从不报告。
 * `result` (`CommandResult`): 命令的结果。
 * `duration_ms` (`int`): 命令的挂钟持续时间（毫秒）。
 * `failure_reason` (`FailureReason | None`): 命令失败的原因，如果未失败，则为 `None`。

返回

 * `dict[str, ParamValue]`: 事件属性，`None` 值已删除。

### build_conversion_result_properties

```python
def build_conversion_result_properties(*, result: CommandResult, duration_ms: int, uploaded_output: bool, uploaded_intermediate_outputs: bool, failure_reason: FailureReason | None = None, output_artifact_count: int | None = None, peak_ram_bytes: int | None = None) -> dict[str, ParamValue]:
```

构建转换结果事件的属性。

参数

 * `result` (`CommandResult`): 转换的结果。
 * `duration_ms` (`int`): 转换的挂钟持续时间（毫秒）。
 * `uploaded_output` (`bool`): 输出模型是否已上传到远程位置。
 * `uploaded_intermediate_outputs` (`bool`): 中间输出是否已上传到远程位置。
 * `failure_reason` (`FailureReason | None`): 转换失败的原因，如果未失败，则为 `None`。
 * `output_artifact_count` (`int | None`): 生成的输出工件数量。在报告之前由
   [bucket_count](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   分桶。
 * `peak_ram_bytes` (`int | None`): 峰值 RAM 使用量（字节）。在报告之前由
   [bucket_memory_bytes](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   分桶。

返回

 * `dict[str, ParamValue]`: 事件属性，`None` 值已删除。

### build_conversion_summary

```python
def build_conversion_summary(cfg: Config, *, platform: Platform, config_source: ConfigSource, archive_output_mode: ArchiveOutputMode, archive_preprocess: bool, main_stage_provided: bool) -> dict[str, ParamValue]:
```

总结遥测的已解析转换配置。

仅报告枚举值、布尔值、数字设置和从配置派生的分桶计数。

参数

 * `cfg` (`Config`): 已解析的转换配置。
 * `platform` (`Platform`): 模型转换的平台。
 * `config_source` (`ConfigSource`): 配置的来源。
 * `archive_output_mode` (`ArchiveOutputMode`): 输出的交付形式。
 * `archive_preprocess` (`bool`): 预处理是否添加到 NN 存档而不是模型。
 * `main_stage_provided` (`bool`): 是否明确提供了主阶段的名称。

返回

 * `dict[str, ParamValue]`: 事件属性，`None` 值已删除。

### build_flow_properties

```python
def build_flow_properties(conversion_run_id: str, flow_step: TelemetryFlowStep, properties: Mapping[str, ParamValue]) -> dict[str, ParamValue]:
```

使用转换流元数据扩展事件属性。

参数

 * `conversion_run_id` (`str`): 将事件与转换运行关联的 ID。
 * `flow_step` (`TelemetryFlowStep`): 事件所属的转换流步骤。
 * `properties` (`Mapping[str, ParamValue]`): 要扩展的事件属性。

返回

 * `dict[str, ParamValue]`: 属性，已添加流名称、转换运行 ID 和流步骤。

### command_failure_reason_from_exception

```python
def command_failure_reason_from_exception(exc: BaseException | None) -> FailureReason | None:
```

从异常中推导出命令失败原因。

参数

 * `exc` (`BaseException | None`): 终止命令的异常，如果命令正常完成，则为 `None`。

返回

 * `FailureReason | None`: 如果命令未失败，则为 `None`；对于键盘中断或退出代码 `130`，则为 `FailureReason.USER_INTERRUPT`；否则为
   `FailureReason.RUNTIME_ERROR`。

### command_result_from_exception

```python
def command_result_from_exception(exc: BaseException | None) -> CommandResult:
```

从结束命令的异常中推导出命令结果。

参数

 * `exc` (`BaseException | None`): 终止命令的异常，如果命令正常完成，则为 `None`。

返回

 * `CommandResult`: 对于没有异常或代码为 `None` 或 `0` 的 `SystemExit`，则为 `CommandResult.SUCCESS`；对于键盘中断或退出代码 `130`，则为
   `CommandResult.INTERRUPTED`；否则为 `CommandResult.FAILED`。

### detect_config_source

```python
def detect_config_source(path: str | None, opts: list[str], archive_cfg: NNArchiveConfig | None) -> ConfigSource:
```

检测转换配置的来源。

参数

 * `path` (`str | None`): 命令行上给定的路径（如果有）。
 * `opts` (`list[str]`): CLI 配置覆盖，作为交替的键和值令牌。
 * `archive_cfg` (`NNArchiveConfig | None`): 从 NN 存档中提取的配置，如果输入是存档或存档目录。

返回

 * `ConfigSource`: 当给定存档配置时为 `ConfigSource.NN_ARCHIVE` 或 `ConfigSource.ARCHIVE_DIRECTORY`；当给定模型文件或 `input_model` 覆盖时为
   `ConfigSource.DIRECT_MODEL_INPUT`；否则为 `ConfigSource.YAML_CONFIG`。

### get_component_telemetry

```python
def get_component_telemetry() -> Telemetry:
```

返回共享的 modelconverter 遥测客户端。

客户端在首次使用时创建，从环境中配置，并以 modelconverter 遥测默认值作为回退。

返回

 * `Telemetry`: 为 modelconverter 注册的 `Telemetry` 实例。

### get_conversion_run_id

```python
def get_conversion_run_id() -> str:
```

返回当前转换运行的 ID。

ID 存储在 `MODELCONVERTER_CONVERSION_RUN_ID` 环境变量中，并在首次使用时生成，以便主机端命令和 Docker 容器内运行的转换报告相同的 ID。

返回

 * `str`: 当前进程的转换运行 ID。

### peak_ram_usage_bytes

```python
def peak_ram_usage_bytes() -> int:
```

返回此进程的峰值 RAM 使用量（字节）。

该值来自 `resource.getrusage`，其 `ru_maxrss` 在 macOS 上以字节报告，在其他地方以 kibibytes 报告。

返回

 * `int`: 峰值驻留集大小（字节）。

### resolve_tool_version

```python
def resolve_tool_version(*, platform: Platform, tool_version: str | None, image: str | None) -> str | None:
```

解析平台转换所用的工具版本。

参数

 * `platform` (`Platform`): 模型转换的平台。
 * `tool_version` (`str | None`): 明确请求的工具版本（如果有）。
 * `image` (`str | None`): 自定义 Docker 镜像（如果有）。

返回

 * `str | None`: 请求的工具版本，或平台的默认版本。当给定带有显式标签的自定义镜像时，返回 `None`，因为版本由该标签决定。

### runtime_failure_reason_from_exception

```python
def runtime_failure_reason_from_exception(exc: BaseException | None, *, phase: ConversionPhase) -> FailureReason | None:
```

从异常中推导出转换失败原因。

参数

 * `exc` (`BaseException | None`): 结束转换的异常，如果转换正常完成，则为 `None`。
 * `phase` (`ConversionPhase`): 转换结束时所处的转换阶段。

返回

 * `FailureReason | None`: 如果没有异常，则为 `None`；对于键盘中断或退出代码 `130`，则为 `FailureReason.USER_INTERRUPT`；否则为与阶段匹配的失败原因。

### telemetry_environment

```python
def telemetry_environment() -> dict[str, str]:
```

收集要转发到容器的遥测变量。

返回

 * `dict[str, str]`: 当前环境中设置的转换运行 ID 和 `LUXONIS_TELEMETRY_*` 变量。未设置的变量将被省略。

## 属性

### COMMAND_EVENT

### CONFIGURED_EVENT

### CONVERSION_RUN_ID_ENV_VAR

### FLOW_NAME

### MODELCONVERTER_TELEMETRY_DEFAULTS

### RESULT_EVENT
