View derived labels
Select from the following methods to view existing derived labels.- Web
- Chronoctl
- API
To view derived labels:
- In the navigation menu select Platform > Derived Labels to view all available derived labels.
- To view values for a derived label, click the caret (>) to expand the label.
-
Click the three vertical dots icon for any label
to take additional actions:
- Click View code config to view a code representation of the derived label. Use the Code Config tool to copy or download the code.
- Click View in Usage Analyzer to open the with the selected derived label.
Manage derived labels
Create, update, and delete derived labels using Terraform, Chronoctl, or the Observability Platform API.Create a derived label
Select from the following methods to create a derived label.- Chronoctl
- Terraform
- API
To create a derived label with Chronoctl, use this command:
-
Run the following command to generate a sample derived label definition you can use
as a template:
In the template,
kind: DerivedLabeldefines an individual derived label. -
With a completed definition, submit it with:
Replace
FILE_NAMEwith the name of the YAML definition file you want to use.
Derived label definition examples
The following definition examples show how to format equivalent derived label definition in Chronoctl, Terraform, and the Observability Platform API.These examples include derived metric labels
and span tags in the same definition. However,
it’s possible to create a definition that only contains derived metric labels,
or that only contains derived span tags.
- Chronoctl
- Terraform
- API
Chronoctl example
env with the
following label mappings for metrics and span tag mappings for traces:
- If a time series contains a label that matches the glob
__name__="grpc_*"or__name__="http_*", the label nameacme_clusterfor that time series maps to the derived labelenv. This derived label name has the following value mappings:- The source globs and values
staging-*,infra, andalphamap to the derived valueinternal. For example, the source label/value pairacme_cluster="staging-demo-playground"maps to the derived label/value pairenv="internal". - The source values
beta,prod, andprod-eumap to the derived valueexternal. For example, the source label/value pairacme_cluster="prod"maps to the derived label/value pairenv="external". - Any other source values stay the same. For example, because
devisn’t listed in the example definition, the source label/value pairacme_cluster="dev"maps to the derived label/value pairenv="dev".
- The source globs and values
- If a time series contains the label
__name__="service_uptime", the label nameacme_test_clusterfor that time series maps to theenvlabel. This derived label name has the following value mappings:- The source values
testanddogfoodingmap to the derived valueinternal. For example, the source label/value pairacme_test_cluster=testmaps to the derived label/value pairenv=internal. - Any other source values stay the same. For example, because
metadataisn’t listed in the example definition, the source label/value pairacme_test_cluster="metadata"maps to the derived label/value pairenv="metadata".
- The source values
- The span tags
environmentandclustermap to the derived span tagenv.
Delete a derived label
Select from the following methods to delete a derived label.- Chronoctl
- Terraform
- API
To delete a derived label with Chronoctl, use this command:Replace
SLUG with the slug of the derived label you want to delete.Use derived labels for metrics
You can use derived labels to simplify label names and values for metrics. In derived label definitions, these definitions are stored in themetric_label object.
The label_name parameter determines the name of the derived metric label.
For each source_label included in a definition, the associated filters
parameter determines which time series the derived label applies to. If a time
series meets one of the filter criteria, the specified source label name from that time
series maps to the name of the derived label.
For each target_value included in a definition, the associated
source_value_globs parameter determines which values from the original source
label map to that target value of the derived label. Any values from the original
source label that aren’t included in a derived label definition stay the same
and map directly to the derived label name.
The value_glob and source_value_globs parameters support
glob syntax.
It’s not possible to create a derived metric label from the names or
values of a different derived label. Each
source_label parameter in your
definitions must reference a persisted, non-derived label name, and each
source_value_globs parameter must reference persisted, non-derived label
values.Best practices
When using derived labels for metrics, Chronosphere recommends following these best practices:- Use mapping labels instead of constructed labels.
- Limit the scope of derived labels as much as possible. This lowers the risk of conflicts and reduces the amount of possible results returned by autocomplete for metric labels in Observability Platform.
- For derived labels that include multiple source keys, the metric filter for each source key should reference a different time series. In other words, don’t create a derived label with two different source keys that could be included in the same time series.
Existing label policy
If a derived label would apply to a time series that already has a persistent, non-derived label with the same name, theexisting_label_policy parameter
determines how to resolve this conflict.
KEEP: The label that already exists is used instead of the derived label. This is the default behavior ifexisting_label_policyis unspecified.OVERRIDE: The derived label replaces the existing label.
existing_label_policy has no effect.
Standardize metric label names
Metrics from different sources might use different label names to describe the same or similar things. You can use derived labels to standardize these names, which makes it easier to run related queries without having to remember which source used which original label name. In the following examples, the source labelsusername and id both
refer to user accounts. The derived label account creates a unified label name
for consistency.
- Chronoctl
- Terraform
- API
Chronoctl example
{__name__="login_count",account="alice"}
returns the same results as {__name__="login_count",username="alice"}. Similarly,
the query {__name__="checkout_attempts",account="12345"} returns the same results as
{__name__="checkout_attempts",id="12345"}.
Because no value mappings were created, the account derived label always
gets its values from the original values of either username or id.
Standardize metric label values
Metrics from a single source might have a large number of values associated with the same label name. You can use derived labels to standardize these values across Observability Platform, which makes it easier to query multiple values at once. In the following examples, a source label namedcode has possible values for
a wide variety of HTTP status codes. The derived label status-level combines
similar HTTP statuses into a fewer number of values.
- Chronoctl
- Terraform
- API
Chronoctl example
{__name__="requests_total",status-level="400"}
returns the same results as {__name__="requests_total",code=~"400|401|403|404"}.
However, only source values that were explicitly mapped were affected. Because
the source value 100 wasn’t mapped, the query
{__name__="requests_total",status-level="100"} returns the same results as
{__name__="requests_total",code="100"}.
Standardize metric label names and values
You can use derived labels to standardize metric label names and values at the same time. In the following examples, the source labelsmenu_item and SKU both refer to
different foods offered at a restaurant. Additionally, both menu_item and SKU
have a wide variety of possible values. The derived label type creates a unified
label name for consistency and also combines similar foods into a fewer number of values.
- Chronoctl
- Terraform
- API
Chronoctl example
{__name__="orders_placed",type="sandwich"}
returns the same results as
{__name__="orders_placed",menu_item=~"BLT|club_sandwich|grilled_cheese"}.
Similarly, the query {__name__="profits_made",type="soup"} returns the same
results as {__name__="profits_made",SKU=~"44444|55555"}.
However, only source values that were explicitly mapped were affected. If
the original menu_item label has a possible value panini, then that value
wouldn’t map to type="sandwich". Instead, the query {__name__="orders_placed",type="panini"}
returns the same results as {__name__="orders_placed",menu_item="panini"}.
Mapping labels versus constructed labels
In derived label definitions, themetric_label object is parent to two child objects: constructed_label and
mapping_label. Each of these child objects offers a different way to define
derived labels for metrics.
- Mapping labels: Defined in
mapping_label. These are the primary way to define derived labels, and are fully supported throughout Observability Platform. - Constructed labels: Defined in
constructed_label. These aren’t fully supported throughout Observability Platform.
Constructed label example
All of the previous examples in this guide use mapping labels. The following example shows how to format a constructed label definition in Chronoctl:Chronoctl example
Chronoctl example
Use derived labels for traces
You can use derived labels to simplify span tags for traces. In derived label definitions, these definitions are stored in thespan_tag object.
The label_name parameter determines the name of the derived span tag,
and the source_tag parameters specify which source tags to map to this
derived span tag.
It’s not possible to create a derived span tag from a different derived span
tag. Each
source_tag parameter in your definitions must reference a persisted,
non-derived span tag.Standardize span tags
In the following truncated examples, the source tagslink and page map to
the derived span tag url.
- Chronoctl
- Terraform
- API
Chronoctl example

