unomiq.unit span attribute to link traces to a unit — a logical entity in your application such as a customer ID, app ID, agent ID, or tenant ID. This allows you to view and filter traces by unit in the Unomiq dashboard or Unomiq Engine API.
You can also optionally set unomiq.parent_unit to create a hierarchy of entities, such as linking an app to the organization it belongs to.
This guide shows how to attach the unomiq.unit and unomiq.parent_unit attributes to your spans.
What is a Unit?
A unit represents the entity that a trace belongs to. Common examples:
The value should be a stable identifier that uniquely represents the entity across requests.
You can optionally set
unomiq.parent_unit alongside unomiq.unit to express a parent-child relationship between entities. For example, in a multi-tenant SaaS application you might set unomiq.unit to an app ID and unomiq.parent_unit to the tenant or organization that app belongs to.
With unomiq-sdk
The unomiq-sdk package handles unit attachment automatically alongside OAuth-authenticated OTLP export. Pass resolve_unit and resolve_parent_unit callables to Unomiq.init() and the SDK attaches unomiq.unit and unomiq.parent_unit to every span.
Global: Automatic via resolve_unit / resolve_parent_unit
Static values:
Manual: Per-span via set_unit / set_parent_unit
For full control, skip the global resolve_unit config and set attributes directly in route handlers:
Disabling Unit Tracking
Omitresolve_unit (or pass None) and the SDK won’t attach unit attributes:
Without unomiq-sdk
If you are not using unomiq-sdk, you can attach unit attributes directly using the OpenTelemetry SDK.
Setting unomiq.unit on Individual Spans
The most straightforward approach is to set the attribute directly on a span:
unomiq.parent_unit is optional. Set it when you want to place the unit within a broader entity hierarchy.
This works with both manual and automatic instrumentation — as long as you have access to a span, you can set the attribute.
Setting unomiq.unit Automatically with a SpanProcessor
To attach the unit to every span without modifying each call site, use a custom SpanProcessor. This is useful when the unit is available from a request context (e.g., an HTTP header, JWT claim, or path parameter).
Example: Resolving Unit from a Flask Request
Example: Resolving Unit from Django
Summary
unomiq.unit must be set as a span attribute. Resource attributes and collector-level processors are not supported for this field.