Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

pkg/ottl: add section about design principles #29424

Merged
merged 7 commits into from
Dec 7, 2023
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion pkg/ottl/LANGUAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

The OTTL grammar includes function invocations, Values and Boolean Expressions. These parts all fit into a Statement, which is the basis of execution in the OTTL.

### Design principles
axw marked this conversation as resolved.
Show resolved Hide resolved

The OTTL is designed according to these principles (excluding user-defined functions):

- *Terminating*: OTTL statements cannot loop forever.
- *Static*: OTTL functions and statements cannot be dynamically loaded or executed.
axw marked this conversation as resolved.
Show resolved Hide resolved

These principles do not apply to user-defined functions.

### Editors

Editors are functions that transform the underlying telemetry payload. They may return a value, but typically do not. There must be a single Editor Invocation in each OTTL statement.
Expand Down Expand Up @@ -288,4 +297,4 @@ It is possible to update the Value in a telemetry field using a Setter. For read

## Logging inside a OTTL function

To emit logs inside a OTTL function, add a parameter of type [`component.TelemetrySettings`](https://pkg.go.dev/go.opentelemetry.io/collector/component#TelemetrySettings) to the function signature. The OTTL will then inject the TelemetrySettings that were passed to `NewParser` into the function. TelemetrySettings can be used to emit logs.
To emit logs inside a OTTL function, add a parameter of type [`component.TelemetrySettings`](https://pkg.go.dev/go.opentelemetry.io/collector/component#TelemetrySettings) to the function signature. The OTTL will then inject the TelemetrySettings that were passed to `NewParser` into the function. TelemetrySettings can be used to emit logs.
11 changes: 11 additions & 0 deletions pkg/ottl/ottlfuncs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,17 @@ This document contains documentation for both types of OTTL functions:
- [Functions](#functions) that transform telemetry.
- [Converters](#converters) that provide utilities for transforming telemetry.

## Design principles
axw marked this conversation as resolved.
Show resolved Hide resolved

For the standard OTTL functions described in this document, we specify design principles to ensure they are always
secure and safe for use:

- Built-in OTTL functions may not access the file system, network, or any other I/O devices.
- Built-in OTTL functions may share information only through their parameters and results.

OTTL functions are implemented in Go, and so are fundamentally limited to what can be implemented by a Go program.
axw marked this conversation as resolved.
Show resolved Hide resolved
User-defined OTTL functions may therefore not adhere the above principles.

## Working with functions

Functions generally expect specific types to be returned by `Paths`.
Expand Down
Loading