diff --git a/pkg/ottl/LANGUAGE.md b/pkg/ottl/LANGUAGE.md index b346f2a4ef6c..05df67e0ffef 100644 --- a/pkg/ottl/LANGUAGE.md +++ b/pkg/ottl/LANGUAGE.md @@ -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. @@ -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. \ No newline at end of file +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. diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index acf2ed70658a..c48d992f47b7 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -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`.