Skip to content

Commit 92437aa

Browse files
edmocostaevan-bradley
edmocosta
and
evan-bradley
authored
[processor/transform] Add new configuration styles documentation (#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 #29017 <!--Please delete paragraphs that you did not use before submitting.--> --------- Co-authored-by: Evan Bradley <[email protected]>
1 parent 00d5d09 commit 92437aa

File tree

10 files changed

+415
-289
lines changed

10 files changed

+415
-289
lines changed

‎pkg/ottl/LANGUAGE.md

+8-6
Original file line numberDiff line numberDiff line change
@@ -118,22 +118,24 @@ Values are passed as function parameters or are used in a Boolean Expression. Va
118118

119119
### Paths
120120

121-
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:
121+
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.
122+
**The interpretation of a Path is NOT implemented by OTTL**. Instead, users must provide a `PathExpressionParser` that OTTL can use to interpret paths.
123+
As a result, the usage of Path segments is determined by the user. However, it is recommended to use them as follows:
122124

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

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

130132
Example Paths
131-
- `name`
132-
- `value_double`
133+
- `metric.name`
134+
- `span.value_double`
133135
- `resource.name`
134136
- `resource.attributes["key"]`
135-
- `attributes["nested"]["values"]`
136-
- `cache["slice"][1]`
137+
- `log.attributes["nested"]["values"]`
138+
- `datapoint.cache["slice"][1]`
137139

138140
#### Contexts
139141

‎pkg/ottl/contexts/ottldatapoint/README.md

+28-25
Large diffs are not rendered by default.

‎pkg/ottl/contexts/ottllog/README.md

+23-20
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Log Context
22

3+
> [!NOTE]
4+
> 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).
5+
36
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.
47

58
## Paths
@@ -11,8 +14,8 @@ The following paths are supported.
1114

1215
| path | field accessed | type |
1316
|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
14-
| 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 |
15-
| 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 |
17+
| 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 |
18+
| 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 |
1619
| resource | resource of the log being processed | pcommon.Resource |
1720
| resource.attributes | resource attributes of the log being processed | pcommon.Map |
1821
| 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 |
@@ -23,24 +26,24 @@ The following paths are supported.
2326
| instrumentation_scope.dropped_attributes_count | number of dropped attributes of the instrumentation scope of the log being processed | int64 |
2427
| instrumentation_scope.attributes | instrumentation scope attributes of the data point being processed | pcommon.Map |
2528
| 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 |
26-
| attributes | attributes of the log being processed | pcommon.Map |
27-
| 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 |
28-
| trace_id | a byte slice representation of the trace id | pcommon.TraceID |
29-
| trace_id.string | a string representation of the trace id | string |
30-
| span_id | a byte slice representation of the span id | pcommon.SpanID |
31-
| span_id.string | a string representation of the span id | string |
32-
| time_unix_nano | the time in unix nano of the log being processed | int64 |
33-
| observed_time_unix_nano | the observed time in unix nano of the log being processed | int64 |
34-
| time | the time in `time.Time` of the log being processed | `time.Time` |
35-
| observed_time | the observed time in `time.Time` of the log being processed | `time.Time` |
36-
| severity_number | the severity numbner of the log being processed | int64 |
37-
| severity_text | the severity text of the log being processed | string |
38-
| body | the body of the log being processed | any |
39-
| 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 |
40-
| 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 |
41-
| body.string | the body of the log being processed represented as a string. When setting must pass a string. | string |
42-
| dropped_attributes_count | the number of dropped attributes of the log being processed | int64 |
43-
| flags | the flags of the log being processed | int64 |
29+
| log.attributes | attributes of the log being processed | pcommon.Map |
30+
| 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 |
31+
| log.trace_id | a byte slice representation of the trace id | pcommon.TraceID |
32+
| log.trace_id.string | a string representation of the trace id | string |
33+
| log.span_id | a byte slice representation of the span id | pcommon.SpanID |
34+
| log.span_id.string | a string representation of the span id | string |
35+
| log.time_unix_nano | the time in unix nano of the log being processed | int64 |
36+
| log.observed_time_unix_nano | the observed time in unix nano of the log being processed | int64 |
37+
| log.time | the time in `time.Time` of the log being processed | `time.Time` |
38+
| log.observed_time | the observed time in `time.Time` of the log being processed | `time.Time` |
39+
| log.severity_number | the severity number of the log being processed | int64 |
40+
| log.severity_text | the severity text of the log being processed | string |
41+
| log.body | the body of the log being processed | any |
42+
| 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 |
43+
| 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 |
44+
| log.body.string | the body of the log being processed represented as a string. When setting must pass a string. | string |
45+
| log.dropped_attributes_count | the number of dropped attributes of the log being processed | int64 |
46+
| log.flags | the flags of the log being processed | int64 |
4447

4548
## Enums
4649

0 commit comments

Comments
 (0)