Skip to content

Commit

Permalink
[processor/transform] Add new configuration styles documentation (ope…
Browse files Browse the repository at this point in the history 
…n-telemetry#37753)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue

open-telemetry#29017

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Co-authored-by: Evan Bradley <[email protected]>
  • Loading branch information
@edmocosta @evan-bradley
edmocosta and evan-bradley authored Feb 12, 2025
1 parent 00d5d09 commit 92437aa
Show file tree
Hide file tree
Showing 10 changed files with 415 additions and 289 deletions.
14 changes: 8 additions & 6 deletions pkg/ottl/LANGUAGE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,22 +118,24 @@ Values are passed as function parameters or are used in a Boolean Expression. Va

### Paths

A Path Value is a reference to a telemetry field. Paths are made up of lowercase identifiers, dots (`.`), and square brackets combined with a string key (`["key"]`) or int key (`[0]`). **The interpretation of a Path is NOT implemented by OTTL.** Instead, the user must provide a `PathExpressionParser` that OTTL can use to interpret paths. As a result, how the Path parts are used is up to the user. However, it is recommended that the parts be used like so:
A Path Value is a reference to a telemetry field. Paths are composed of lowercase identifiers, dots (`.`), and square brackets containing either a string key (`["key"]`), an integer key (`[0]`), or an expression that might be a [Converter](#converters) or another Path.
**The interpretation of a Path is NOT implemented by OTTL**. Instead, users must provide a `PathExpressionParser` that OTTL can use to interpret paths.
As a result, the usage of Path segments is determined by the user. However, it is recommended to use them as follows:

- Identifiers are used to map to a telemetry field.
- Dots (`.`) are used to separate nested fields.
- Dots (`.`) are used to separate nested fields, please note that the first path segment is interpreted by OTTL as the context identifier.
- Square brackets and keys (`["key"]`) are used to access values within maps.

When accessing a map's value, if the given key does not exist, `nil` will be returned.
This can be used to check for the presence of a key within a map within a [Boolean Expression](#boolean-expressions).

Example Paths
- `name`
- `value_double`
- `metric.name`
- `span.value_double`
- `resource.name`
- `resource.attributes["key"]`
- `attributes["nested"]["values"]`
- `cache["slice"][1]`
- `log.attributes["nested"]["values"]`
- `datapoint.cache["slice"][1]`

#### Contexts

Expand Down
53 changes: 28 additions & 25 deletions pkg/ottl/contexts/ottldatapoint/README.md
View file

Large diffs are not rendered by default.

43 changes: 23 additions & 20 deletions pkg/ottl/contexts/ottllog/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Log Context

> [!NOTE]
> This documentation applies only to version `0.120.0` and later. For information on earlier versions, please refer to the previous [documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/release/0.119.x/pkg/ottl/contexts/ottllog/README.md).
The Log Context is a Context implementation for [pdata Logs](https://github.com/open-telemetry/opentelemetry-collector/tree/main/pdata/plog), the collector's internal representation for OTLP log data. This Context should be used when interacted with OTLP logs.

## Paths
Expand All @@ -11,8 +14,8 @@ The following paths are supported.

| path | field accessed | type |
|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| cache | the value of the current transform context's temporary cache. cache can be used as a temporary placeholder for data during complex transformations | pcommon.Map |
| cache\[""\] | the value of an item in cache. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| log.cache | the value of the current transform context's temporary cache. cache can be used as a temporary placeholder for data during complex transformations | pcommon.Map |
| log.cache\[""\] | the value of an item in cache. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| resource | resource of the log being processed | pcommon.Resource |
| resource.attributes | resource attributes of the log being processed | pcommon.Map |
| resource.attributes\[""\] | the value of the resource attribute of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
Expand All @@ -23,24 +26,24 @@ The following paths are supported.
| instrumentation_scope.dropped_attributes_count | number of dropped attributes of the instrumentation scope of the log being processed | int64 |
| instrumentation_scope.attributes | instrumentation scope attributes of the data point being processed | pcommon.Map |
| instrumentation_scope.attributes\[""\] | the value of the instrumentation scope attribute of the data point being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| attributes | attributes of the log being processed | pcommon.Map |
| attributes\[""\] | the value of the attribute of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| trace_id | a byte slice representation of the trace id | pcommon.TraceID |
| trace_id.string | a string representation of the trace id | string |
| span_id | a byte slice representation of the span id | pcommon.SpanID |
| span_id.string | a string representation of the span id | string |
| time_unix_nano | the time in unix nano of the log being processed | int64 |
| observed_time_unix_nano | the observed time in unix nano of the log being processed | int64 |
| time | the time in `time.Time` of the log being processed | `time.Time` |
| observed_time | the observed time in `time.Time` of the log being processed | `time.Time` |
| severity_number | the severity numbner of the log being processed | int64 |
| severity_text | the severity text of the log being processed | string |
| body | the body of the log being processed | any |
| body\[""\] | a value in a map body of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| body\[\] | a value in a slice body of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| body.string | the body of the log being processed represented as a string. When setting must pass a string. | string |
| dropped_attributes_count | the number of dropped attributes of the log being processed | int64 |
| flags | the flags of the log being processed | int64 |
| log.attributes | attributes of the log being processed | pcommon.Map |
| log.attributes\[""\] | the value of the attribute of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| log.trace_id | a byte slice representation of the trace id | pcommon.TraceID |
| log.trace_id.string | a string representation of the trace id | string |
| log.span_id | a byte slice representation of the span id | pcommon.SpanID |
| log.span_id.string | a string representation of the span id | string |
| log.time_unix_nano | the time in unix nano of the log being processed | int64 |
| log.observed_time_unix_nano | the observed time in unix nano of the log being processed | int64 |
| log.time | the time in `time.Time` of the log being processed | `time.Time` |
| log.observed_time | the observed time in `time.Time` of the log being processed | `time.Time` |
| log.severity_number | the severity number of the log being processed | int64 |
| log.severity_text | the severity text of the log being processed | string |
| log.body | the body of the log being processed | any |
| log.body\[""\] | a value in a map body of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| log.body\[\] | a value in a slice body of the log being processed. Supports multiple indexes to access nested fields. | string, bool, int64, float64, pcommon.Map, pcommon.Slice, []byte or nil |
| log.body.string | the body of the log being processed represented as a string. When setting must pass a string. | string |
| log.dropped_attributes_count | the number of dropped attributes of the log being processed | int64 |
| log.flags | the flags of the log being processed | int64 |

## Enums

Expand Down
Loading

0 comments on commit 92437aa

Please sign in to comment.