From d6714baad7539d067f2c988bf60570bae452a828 Mon Sep 17 00:00:00 2001 From: Ruben Vargas Date: Thu, 19 Oct 2023 13:44:51 -0600 Subject: [PATCH 1/2] Add OpenTelemetry processors documentation Signed-off-by: Ruben Vargas --- .../distr-tracing-otel-config-collector.adoc | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) diff --git a/modules/distr-tracing-otel-config-collector.adoc b/modules/distr-tracing-otel-config-collector.adoc index 3cafd83f0ef1..ea99b49dfab7 100644 --- a/modules/distr-tracing-otel-config-collector.adoc +++ b/modules/distr-tracing-otel-config-collector.adoc @@ -332,6 +332,198 @@ rules: processors: [resourcedetection] ---- +==== Resource processor + +The Resource processor applies changes on resource attributes + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: traces, metrics, logs + +.OpenTelemetry Collector using the Resource Detection processor +[source,yaml] +---- + config: | + processor: + attributes: + - key: cloud.availability_zone + value: "zone-1" + action: upsert + - key: k8s.cluster.name + from_attribute: k8s-cluster + action: insert + - key: redundant-attribute + action: delete +---- + +Attributes represent the actions that will be applied to the resource attributes like delete the attribute, insert the atribute or upsert it. + + +==== Span Processor + + +This processor modifies the span name based on its attributes or extract span attributes from the span name. It also could change span status.It can also include or exclude spans. + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: traces + +For span renaming need to specify with attributes the new name is gonna be created, to do that use `from_attributes` configuration. + +.OpenTelemetry Collector using the Span Processor for renaming span +[source,yaml] +---- + config: | + processor: + span: + name: + from_attributes: [, , ...] <1> + separator: <2> +---- +<1> Defined the keys that will conform the new span name +<2> Optionally a separator + +Other uses of this processor includes the ability to extract atributes from the span name + +.OpenTelemetry Collector using the Span Processor for extracting attributes from span name +[source,yaml] +---- + config: | + processor: + # Let's assume input span name is /api/v1/document/12345678/update + # Applying the following results in output span name /api/v1/document/{documentId}/update + # and will add a new attribute "documentId"="12345678" to the span. + span/to_attributes: + name: + to_attributes: + rules: + - ^\/api\/v1\/document\/(?P.*)\/update$ <1> +---- +<1> This rule defined how the extraction will be executed, we can define more rules, in this case if the regexp match the name + a documentID attibute will be created. + +The span status can also be modified in the following way + +.OpenTelemetry Collector using the Span Processor for status change +[source,yaml] +---- + config: | + processor: + span/set_status: + status: + code: Error + description: "some error description" +---- + + +==== Kubernetes Attributes Processor + +The Kubernetes attributes processor enables automatic configuration of spans, metrics, and log resource attributes using Kubernetes metadata. + +This processor automatically identifies Kubernetes resources, extracts metadata from them, and incorporates this extracted metadata as resource attributes into relevant spans, metrics, and logs. It utilizes the Kubernetes API to discover all pods operating within a cluster, maintaining records of their IP addresses, pod UIDs, and other relevant metadata. + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: logs, metrics, traces + +.{product-title} minimum permissions required to make the Kubernetes Attributes Processor work: +[source,yaml] +---- +kind: ClusterRole +metadata: + name: otel-collector +rules: + - apiGroups: [''] + resources: ['pods', 'namespaces'] + verbs: ['get', 'watch', 'list'] +---- + +.OpenTelemetry Collector using the Kubernetes Attributes processor +[source,yaml] +---- + config: | + processors: + k8sattributes: + filter: + node_from_env_var: KUBE_NODE_NAME +---- + +=== Resource Detection Processor + +The resource detection processor is employed to identify resource details from the host, structured in accordance with OpenTelemetry's resource semantic conventions. It then appends or replaces the resource value within telemetry data with this gathered information. + + +This processor supports multiple detectors like docker metadata which extract information from the docker daemon, GCP, AWS for extracting information from those enviromnents. A common usage of this processor is whith environment variable detector, it will read the informatiton from the `OTEL_RESOURCE_ATTRIBUTES` environment variable that should be in the format `=,=,...` + + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: logs, metrics, traces + + +.OpenTelemetry Collector using the Resource Detection Processor with environment variable detector +[source,yaml] +---- + config: | + processors: + resourcedetection/env: + detectors: [env] <1> + timeout: 2s + override: false +---- +<1> Specify which detector to use, in this case environment detector + +=== Filter Processor + +The filter processor leverages the OpenTelemetry Transformation Language to establish criteria for deciding when to discard telemetry data. If any of these conditions are satisfied, the telemetry data is discarded, with each condition being combined through a logical OR operation. + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: logs, metrics, traces + +.OpenTelemetry Collector custom resource with an enabled OTLP exporter +[source,yaml] +---- +config: | + processors: + filter/ottl: + error_mode: ignore <1> + traces: + span: + - 'attributes["container.name"] == "app_container_1"' <2> + - 'resource.attributes["host.name"] == "localhost"' <3> +---- +<1> Define error mode, there are two possible values for this, ignore which ignores errors returned by conditions and continues on to the next conditionm and propagate which returns the error up the pipeline. This will result in the payload being dropped from the collector. +<2> Filter the spans that have the attribute `container.name == app_container_1` +<3> Filter the spans that have the resource attribute `host.name == localhost` + +=== Routing processor + +Routes logs, metrics or traces to specific exporters. This processor will either read a header from the incoming HTTP request (gRPC or plain HTTP), or it will read a resource attribute, and direct the trace information to specific exporters based on the value read. + +* Support level: link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] +* Supported signals: logs, metrics, traces + +.OpenTelemetry Collector custom resource with an enabled OTLP exporter +[source,yaml] +---- +config: | + processors: + routing: + from_attribute: X-Tenant <1> + default_exporters: <2> + - jaeger + table: <3> + - value: acme + exporters: [jaeger/acme] + exporters: + jaeger: + endpoint: localhost:14250 + jaeger/acme: + endpoint: localhost:24250 +---- +<1> Define HTTP header name for lookup value for doing the route. +<2> Default exporter when the attribute value is not present in the tablel +<3> Table that defines which values are gonna be routed to which exporters + + +Optionally can be set `attribute_source` configuratiion, which defines where to look for the attribute in from_attribute. The allowed values are: context to search the context, which includes HTTP headers or resource to search the resource attributes. + [id="exporters_{context}"] === Exporters From b48245f0bb84fe47d4d858f54bb8da19d7afd289 Mon Sep 17 00:00:00 2001 From: Ruben Vargas Date: Thu, 19 Oct 2023 23:42:29 -0600 Subject: [PATCH 2/2] add Attributes processor Signed-off-by: Ruben Vargas --- .../distr-tracing-otel-config-collector.adoc | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/modules/distr-tracing-otel-config-collector.adoc b/modules/distr-tracing-otel-config-collector.adoc index ea99b49dfab7..a6d43e4136be 100644 --- a/modules/distr-tracing-otel-config-collector.adoc +++ b/modules/distr-tracing-otel-config-collector.adoc @@ -331,6 +331,46 @@ rules: metrics: processors: [resourcedetection] ---- +==== Attributes Processor + +The Attributes Processor has the ability to modifying attributes of a span, log, or metric. This processor can be configuret to filter and match input data and determine whether they should be included or excluded for specific actions. + +The processor operates on a list of actions, executing them in the order specified in the configuration. The following actions are supported: + +* Insert: Inserts a new attribute into the input data when the specified key does not already exist. +* Update: Updates an attribute in the input data if the key already exists. +* Upsert: Combines the insert and update actions. It inserts a new attribute if the key doesn't exist, and updates the attribute if the key does exist. +* Delete: Removes an attribute from the input data. +* Hash: Performs a SHA1 hash on an existing attribute value. +* Extract: Extracts values using a regular expression rule from the input key to target keys defined in the rule. If a target key already exists, it will be overridden. Note: This behavior is similar to the Span Processor's to_attributes setting with the existing attribute as the source. +* Convert: Converts an existing attribute to a specified type. + +.OpenTelemetry Collector using the Attributes Processor +[source,yaml] +---- + config: | + processors: + attributes/example: + actions: + - key: db.table + action: delete + - key: redacted_span + value: true + action: upsert + - key: copy_key + from_attribute: key_original + action: update + - key: account_id + value: 2245 + action: insert + - key: account_password + action: delete + - key: account_email + action: hash + - key: http.status_code + action: convert + converted_type: int +---- ==== Resource processor