OBSDOCS-1151: Add documentation for transform processor

Signed-off-by: Ruben Vargas [email protected]

Author: max-cx

observability/otel/otel-collector/otel-collector-processors.adoc

@@ -394,7 +394,7 @@ config: |
 <2> The default exporter when the attribute value is not present in the table in the next section.
 <3> The table that defines which values are to be routed to which exporters.
 
-You can optionally create an `attribute_source` configuration, which defines where to look for the attribute in `from_attribute`. The allowed value is `context` to search the context, which includes the HTTP headers, or `resource` to search the resource attributes.
+Optionally, you can create an `attribute_source` configuration, which defines where to look for the attribute that you specify in the `from_attribute` field. The supported values are `context` for searching the context including the HTTP headers, and `resource` for searching the resource attributes.
 
 [id="cumulativetodelta-processor_{context}"]
 == Cumulative-to-Delta Processor
@@ -453,3 +453,108 @@ processors:
 ----
 <1> Specifies attribute keys to group by.
 <2> If a processed span, log record, or metric datapoint contains at least one of the specified attribute keys, it is reassigned to a Resource that shares the same attribute values; and if no such Resource exists, a new one is created. If none of the specified attribute keys is present in the processed span, log record, or metric datapoint, then it remains associated with its current Resource. Multiple instances of the same Resource are consolidated.
+
+[id="transform-processor_{context}"]
+== Transform Processor
+
+The Transform Processor enables modification of telemetry data according to specified rules and in the link:https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/ottl[OpenTelemetry Transformation Language (OTTL)].
+For each signal type, the processor processes a series of conditions and statements associated with a specific OTTL Context type and then executes them in sequence on incoming telemetry data as specified in the configuration.
+Each condition and statement can access and modify telemetry data by using various functions, allowing conditions to dictate if a function is to be executed.
+
+All statements are written in the OTTL.
+You can configure multiple context statements for different signals, traces, metrics, and logs.
+The value of the `context` type specifies which OTTL Context the processor must use when interpreting the associated statements.
+
+:FeatureName: The Transform Processor
+include::snippets/technology-preview.adoc[]
+
+.Configuration summary
+[source,yaml]
+----
+# ...
+config: |
+  processors:
+    transform:
+      error_mode: ignore # <1>
+      <trace|metric|log>_statements: # <2>
+        - context: <string> # <3>
+          conditions:  # <4>
+            - <string>
+            - <string>
+          statements: # <5>
+            - <string>
+            - <string>
+            - <string>
+        - context: <string>
+          statements:
+            - <string>
+            - <string>
+            - <string>
+# ...
+----
+<1> Optional: See the following table "Values for the optional `error_mode` field".
+<2> Indicates a signal to be transformed.
+<3> See the following table "Values for the `context` field".
+<4> Optional: Conditions for performing a transformation.
+
+.Configuration example
+[source,yaml]
+----
+# ...
+config: |
+  transform:
+    error_mode: ignore
+    trace_statements: # <1>
+      - context: resource
+        statements:
+          - keep_keys(attributes, ["service.name", "service.namespace", "cloud.region", "process.command_line"]) # <2>
+          - replace_pattern(attributes["process.command_line"], "password\\=[^\\s]*(\\s?)", "password=***") # <3>
+          - limit(attributes, 100, [])
+          - truncate_all(attributes, 4096)
+      - context: span # <4>
+        statements:
+          - set(status.code, 1) where attributes["http.path"] == "/health"
+          - set(name, attributes["http.route"])
+          - replace_match(attributes["http.target"], "/user/*/list/*", "/user/{userId}/list/{listId}")
+          - limit(attributes, 100, [])
+          - truncate_all(attributes, 4096)
+# ...
+----
+<1> Transforms a trace signal.
+<2> Keeps keys on the resources.
+<3> Replaces attributes and replaces string characters in password fields with asterisks.
+<4> Performs transformations at the span level.
+
+.Values for the `context` field
+[options="header"]
+[cols="a,a"]
+|===
+|Signal Statement |Valid Contexts
+
+|`trace_statements`
+|`resource`, `scope`, `span`, `spanevent`
+
+|`metric_statements`
+|`resource`, `scope`, `metric`, `datapoint`
+
+|`log_statements`
+|`resource`, `scope`, `log`
+
+|===
+
+.Values for the optional `error_mode` field
+[options="header"]
+[cols="a,a"]
+|===
+|Value |Description
+
+|`ignore`
+|Ignores and logs errors returned by statements and then continues to the next statement.
+
+|`silent`
+|Ignores and doesn't log errors returned by statements and then continues to the next statement.
+
+|`propagate`
+|Returns errors up the pipeline and drops the payload. Implicit default.
+
+|===