# telemetry

Python API: `modelconverter.utils.telemetry`

Telemetry events reported by the modelconverter CLI.

Builds the property payloads that the CLI sends through `luxonis_ml.telemetry` for a conversion run: which command ran, how the
conversion was configured, and how it ended. The reported values are enum values, booleans, numeric settings and bucketed counts
derived from the configuration rather than raw model names, paths or file contents. A conversion run id, propagated through an
environment variable, ties the host-side command event to the events emitted from inside the conversion Docker container.

## Classes

### ArchiveOutputMode

Form in which the converted model is delivered.

Either a plain model file (`native`) or a Luxonis NN Archive (`nn_archive`).

#### Attributes

##### NATIVE

##### NN_ARCHIVE

### CalibrationSource

Kind of calibration data configured for an input.

#### Attributes

##### IMAGE_DIRECTORY

##### RANDOM

##### REMOTE_LINK

### CommandName

CLI command a command telemetry event was emitted for.

#### Attributes

##### CONVERT

### CommandResult

Outcome of a command or of a conversion run.

#### Attributes

##### FAILED

##### INTERRUPTED

##### SUCCESS

### ConfigSource

Origin of the configuration used for a conversion.

#### Attributes

##### ARCHIVE_DIRECTORY

##### DIRECT_MODEL_INPUT

##### NN_ARCHIVE

##### YAML_CONFIG

### ConversionPhase

Phase of the conversion that was active when it ended.

#### Attributes

##### CONFIGURATION

##### CONVERSION

##### UPLOAD_INTERMEDIATE

##### UPLOAD_OUTPUT

### FailureReason

Reason a command or a conversion run did not succeed.

#### Attributes

##### CONFIG_ERROR

##### CONVERSION_ERROR

##### RUNTIME_ERROR

##### UPLOAD_ERROR

##### USER_INTERRUPT

### TelemetryFlowStep

Step of the conversion lifecycle a flow event belongs to.

#### Attributes

##### CONFIGURATION_RESOLVED

##### RESULT_RECORDED

## Functions

### bucket_count

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

Reduce a count to a coarse bucket label.

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

Parameters

 * `value` (`int | None`): Count to report. Bucketing keeps a telemetry event from carrying the exact shape of the converted model.

Returns

 * `str | None`: One of `"0"`, `"1"`, `"2_4"` or `"5_plus"`, or `None` if `value` is `None`.

### bucket_memory_bytes

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

Reduce a memory size in bytes to a coarse bucket label.

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

Parameters

 * `value` (`int | None`): Memory size in bytes, as
   [peak_ram_usage_bytes](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   measures it.

Returns

 * `str | None`: One of `"under_512m"`, `"512m_1g"`, `"1g_4g"` or `"above_4g"`, or `None` if `value` is `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]:
```

Build the properties of the command telemetry event.

Parameters

 * `conversion_run_id` (`str`): Id tying the event to the conversion run.
 * `platform` (`Platform`): Platform the command was invoked for.
 * `runs_in_docker` (`bool`): Whether the conversion runs inside a Docker container.
 * `dev_image` (`bool`): Whether the development image tag is used.
 * `gpu_enabled` (`bool`): Whether GPU access was requested.
 * `tool_version` (`str | None`): Resolved tool version of the platform, or `None` if it is determined by a custom image tag.
 * `custom_image_provided` (`bool`): Whether a custom Docker image was given. The image name itself is never reported.
 * `memory_limit_set` (`bool`): Whether a memory limit was given. The limit itself is never reported.
 * `cpu_limit_set` (`bool`): Whether a CPU limit was given. The limit itself is never reported.
 * `result` (`CommandResult`): Outcome of the command.
 * `duration_ms` (`int`): Wall-clock duration of the command in milliseconds.
 * `failure_reason` (`FailureReason | None`): Reason the command failed, or `None` if it did not fail.

Returns

 * `dict[str, ParamValue]`: Event properties, with the `None` values dropped.

### 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]:
```

Build the properties of the conversion result event.

Parameters

 * `result` (`CommandResult`): Outcome of the conversion.
 * `duration_ms` (`int`): Wall-clock duration of the conversion in milliseconds.
 * `uploaded_output` (`bool`): Whether the output models were uploaded to a remote location.
 * `uploaded_intermediate_outputs` (`bool`): Whether the intermediate outputs were uploaded to a remote location.
 * `failure_reason` (`FailureReason | None`): Reason the conversion failed, or `None` if it did not fail.
 * `output_artifact_count` (`int | None`): Number of produced output artifacts. Bucketed by
   [bucket_count](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   before it is reported.
 * `peak_ram_bytes` (`int | None`): Peak RAM usage in bytes. Bucketed by
   [bucket_memory_bytes](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/telemetry.md)
   before it is reported.

Returns

 * `dict[str, ParamValue]`: Event properties, with the `None` values dropped.

### 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]:
```

Summarize a resolved conversion configuration for telemetry.

Only enum values, booleans, numeric settings and bucketed counts derived from the configuration are reported.

Parameters

 * `cfg` (`Config`): Resolved conversion configuration.
 * `platform` (`Platform`): Platform the model is converted for.
 * `config_source` (`ConfigSource`): Where the configuration came from.
 * `archive_output_mode` (`ArchiveOutputMode`): Form in which the outputs are delivered.
 * `archive_preprocess` (`bool`): Whether the pre-processing is added to the NN archive instead of the model.
 * `main_stage_provided` (`bool`): Whether the name of the main stage was given explicitly.

Returns

 * `dict[str, ParamValue]`: Event properties, with the `None` values dropped.

### build_flow_properties

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

Extend event properties with the conversion flow metadata.

Parameters

 * `conversion_run_id` (`str`): Id tying the event to the conversion run.
 * `flow_step` (`TelemetryFlowStep`): Step of the conversion flow the event belongs to.
 * `properties` (`Mapping[str, ParamValue]`): Event properties to extend.

Returns

 * `dict[str, ParamValue]`: The properties, with the flow name, the conversion run id and the flow step added.

### command_failure_reason_from_exception

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

Derive the command failure reason from the exception.

Parameters

 * `exc` (`BaseException | None`): Exception that terminated the command, or `None` if the command completed normally.

Returns

 * `FailureReason | None`: `None` if the command did not fail, `FailureReason.USER_INTERRUPT` for a keyboard interrupt or an exit
   code of `130`, and `FailureReason.RUNTIME_ERROR` otherwise.

### command_result_from_exception

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

Derive the command result from the exception that ended it.

Parameters

 * `exc` (`BaseException | None`): Exception that terminated the command, or `None` if the command completed normally.

Returns

 * `CommandResult`: `CommandResult.SUCCESS` for no exception or a `SystemExit` with code `None` or `0`,
   `CommandResult.INTERRUPTED` for a keyboard interrupt or an exit code of `130`, and `CommandResult.FAILED` otherwise.

### detect_config_source

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

Detect where the conversion configuration came from.

Parameters

 * `path` (`str | None`): Path given on the command line, if any.
 * `opts` (`list[str]`): CLI configuration overrides as alternating key and value tokens.
 * `archive_cfg` (`NNArchiveConfig | None`): Configuration extracted from an NN archive, if the input was an archive or an archive
   directory.

Returns

 * `ConfigSource`: `ConfigSource.NN_ARCHIVE` or `ConfigSource.ARCHIVE_DIRECTORY` when an archive configuration is given,
   `ConfigSource.DIRECT_MODEL_INPUT` when a model file or an `input_model` override is given, and `ConfigSource.YAML_CONFIG`
   otherwise.

### get_component_telemetry

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

Return the shared modelconverter telemetry client.

The client is created on first use, configured from the environment with the modelconverter telemetry defaults as fallback.

Returns

 * `Telemetry`: The `Telemetry` instance registered for modelconverter.

### get_conversion_run_id

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

Return the id of the current conversion run.

The id is stored in the `MODELCONVERTER_CONVERSION_RUN_ID` environment variable and generated on first use, so that the host-side
command and the conversion running inside the Docker container report the same id.

Returns

 * `str`: Conversion run id for the current process.

### peak_ram_usage_bytes

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

Return the peak RAM usage of this process in bytes.

The value comes from `resource.getrusage`, whose `ru_maxrss` is reported in bytes on macOS and in kibibytes elsewhere.

Returns

 * `int`: Peak resident set size in bytes.

### resolve_tool_version

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

Resolve the tool version the platform is converted with.

Parameters

 * `platform` (`Platform`): Platform the model is converted for.
 * `tool_version` (`str | None`): Explicitly requested tool version, if any.
 * `image` (`str | None`): Custom Docker image, if any.

Returns

 * `str | None`: The requested tool version, or the default one for the platform. `None` is returned when a custom image with an
   explicit tag is given, since the version is then decided by that tag.

### runtime_failure_reason_from_exception

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

Derive the conversion failure reason from the exception.

Parameters

 * `exc` (`BaseException | None`): Exception that ended the conversion, or `None` if the conversion finished normally.
 * `phase` (`ConversionPhase`): Conversion phase that was active when it ended.

Returns

 * `FailureReason | None`: `None` if there was no exception, `FailureReason.USER_INTERRUPT` for a keyboard interrupt or an exit
   code of `130`, and otherwise the failure reason matching the phase.

### telemetry_environment

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

Collect the telemetry variables to forward to the container.

Returns

 * `dict[str, str]`: The conversion run id and `LUXONIS_TELEMETRY_*` variables that are set in the current environment. Unset
   variables are omitted.

## Attributes

### COMMAND_EVENT

### CONFIGURED_EVENT

### CONVERSION_RUN_ID_ENV_VAR

### FLOW_NAME

### MODELCONVERTER_TELEMETRY_DEFAULTS

### RESULT_EVENT