Derived labels are a construct specifically designed for Chronosphere
Observability Platform that let you standardize data in Observability Platform
without modifying that data permanently. Use derived labels to reduce the
complexity of label names and values for metrics, and to simplify span tags for
traces.
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
Telemetry Usage Analyzer with the selected derived
label.
If a derived label is being used as a pinned scope, click
Configure to navigate to the Scope Configuration page. From there, you can
configure a scope.
To display all derived labels with Chronoctl, use this command:
Copy
Ask AI
chronoctl derived-labels list
To list specific derived labels using their slugs:
Copy
Ask AI
chronoctl derived-labels list --slugs slug_name_1,slug_name_2
To complete this action with the Chronosphere API, use the
ListDerivedLabels endpoint.Because the Chronosphere API requires authentication, include an API token with your
curl request, as shown in the following example. For more details, see
Create an API token.
Create, update, and delete derived labels using
Terraform, Chronoctl, or the
Observability Platform API.
Creating, modifying, or deleting a derived label can cause unexpected behavior in any
location that label was used. Adding a derived label is adding an extra label. Rules
that expect a specific set of labels might not match when the derived label is
present.
Select from the following methods to create a derived label.
Chronoctl
Terraform
API
To create a derived label with Chronoctl, use this command:
Copy
Ask AI
chronoctl derived-labels create
Run the following command to generate a sample derived label definition you can use
as a template:
Copy
Ask AI
chronoctl derived-labels scaffold
In the template, kind: DerivedLabel defines an individual derived label.
With a completed definition, submit it with:
Copy
Ask AI
chronoctl derived-labels create -f FILE_NAME.yaml
Replace FILE_NAME with the name of the YAML definition file you want to use.
See the Chronoctl definition example for a
completed derived label definition.
When you run terraform plan to generate an execution plan, Chronosphere automatically
tests configurations that include notification policies by submitting them as dry runs.
For details, see the
Terraform provider
documentation.
Create or edit a Terraform file and add the definition by using the
chronosphere_derived_label type, followed by a name in a resource
declaration.
Run this command to apply the changes:
Copy
Ask AI
terraform apply
See the Terraform definition example for a
completed derived label definition.
To complete this action with the Chronosphere API, use the
CreateDerivedLabel endpoint.Because the Chronosphere API requires authentication, include an API token with your
curl request, as shown in the following example. For more details, see
Create an API token.
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.
These examples create a derived label named 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 name acme_cluster for
that time series maps to the derived label env. This derived label name has
the following value mappings:
The source globs and values staging-*, infra, and alpha map to the derived value
internal. For example, the source label/value pair acme_cluster="staging-demo-playground"
maps to the derived label/value pair env="internal".
The source values beta, prod, and prod-eu map to the derived value
external. For example, the source label/value pair acme_cluster="prod"
maps to the derived label/value pair env="external".
Any other source values stay the same. For example, because dev isn’t
listed in the example definition, the source label/value pair acme_cluster="dev"
maps to the derived label/value pair env="dev".
If a time series contains the label __name__="service_uptime", the label
name acme_test_cluster for that time series maps to the env label. This
derived label name has the following value mappings:
The source values test and dogfooding map to the derived value internal.
For example, the source label/value pair acme_test_cluster=test maps to
the derived label/value pair env=internal.
Any other source values stay the same. For example, because metadata isn’t
listed in the example definition, the source label/value pair
acme_test_cluster="metadata" maps to the derived label/value pair env="metadata".
The span tags environment and cluster map to the derived span tag env.
Edit your Terraform configuration file to remove the pre-existing resource
definition.
Run this command to remove the resource from Observability Platform:
Copy
Ask AI
terraform apply
To complete this action with the Chronosphere API, use the
DeleteDerivedLabel endpoint.Because the Chronosphere API requires authentication, include an API token with your
curl request, as shown in the following example. For more details, see
Create an API token.
You can use derived labels to simplify label names and values for metrics. In
derived label definitions, these
definitions are stored in the metric_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.
After you define a derived metric label, you can reference that new label in
Metrics Explorer queries in the
same way that you can reference persisted, non-derived metrics labels. Additionally,
these derived metric labels will appear throughout Observability Platform in the
same places as persisted metric labels, like
Metrics Catalog.
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.
If a derived label would apply to a time series that already has a persistent,
non-derived label with the same name, the existing_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 if existing_label_policy is unspecified.
OVERRIDE: The derived label replaces the existing label.
A derived label that applies to one time series can have the same name as an
existing label on a different time series. Unless the identical labels are
part of the same time series, existing_label_policy has no effect.
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 labels username and id both
refer to user accounts. The derived label account creates a unified label name
for consistency.
After creating this derived label, the query {__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.
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 named code 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.
After creating this derived label, the query {__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"}.
You can use derived labels to standardize metric label names and values at the same time.In the following examples, the source labels menu_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.
After creating this derived label, the query {__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"}.
In derived label definitions, the
metric_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.
Chronosphere recommends using mapping derived labels instead of constructed derived
labels. Although they follow different syntax in their definitions, it’s possible
to create equivalent derived labels for metrics by using either mapping labels
or constructed labels. Additionally, constructed labels behave less precisely
and can have unexpected conflicts with other persisted or derived labels.
You can use derived labels to simplify span tags for traces. In
derived label definitions, these
definitions are stored in the span_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.
After you define a derived span tag, you can reference that new span tag in
Trace Explorer queries in the same way
that you can reference persisted, non-derived span tags. Additionally, those
derived span tags will appear throughout Observability Platform in the same places
as persisted span tags, like DDx output.