Skip to content

Commit

Permalink
pkg/ottl: add section about design principles (open-telemetry#29424)
Browse files Browse the repository at this point in the history
**Description:**

Drawing inspiration from
https://github.com/bazelbuild/starlark#design-principles and
https://github.com/google/cel-spec/blob/master/doc/langdef.md#overview,
add a brief section about design principles.

The aim of this is to ensure OTTL is and remains safe for execution of
untrusted programs in multi-tenant systems, where tenants can provide
their own OTTL programs.

---------

Co-authored-by: Evan Bradley <[email protected]>
  • Loading branch information
axw and evan-bradley committed Dec 7, 2023
1 parent 541bbd1 commit 7ac560f
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 1 deletion.
9 changes: 8 additions & 1 deletion pkg/ottl/LANGUAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@

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

OTTL is intended as a domain-specific language (DSL) for telemetry mutation and generation,
and is not intended to be used as a general-purpose programming language.

OTTL has been designed to work directly with [pdata](https://github.com/open-telemetry/opentelemetry-collector/tree/main/pdata), but can operate on other data formats.

### 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 +295,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.
12 changes: 12 additions & 0 deletions pkg/ottl/ottlfuncs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,18 @@ 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

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.
- Built-in OTTL functions must be terminating; they must not loop forever.

OTTL functions are implemented in Go, and so are only limited by what can be implemented in a Go program.
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

0 comments on commit 7ac560f

Please sign in to comment.