--- title: Expression Language for Live Debugger and Dynamic Instrumentation description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > APM > Application Instrumentation > Dynamic Instrumentation > Expression Language for Live Debugger and Dynamic Instrumentation --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Expression Language for Live Debugger and Dynamic Instrumentation {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} ## Overview{% #overview %} [Live Debugger](https://docs.datadoghq.com/tracing/live_debugger.md) and [Dynamic Instrumentation](https://docs.datadoghq.com/dynamic_instrumentation.md) use this expression language to read values from running code and define conditions, metrics, and span tags. The expression language supports access to local variables, method parameters, and nested object fields, along with comparison and logical operators. It borrows syntax from common programming languages but has its own rules. Examples: - `someVar.someField` - `request.headers["Host"]` - `any(post.tags, {@it == "debugger"})` - `@duration > 10 && len(p.data) < 100` Expression support depends on the runtime version and instrumentation location. Generally, the Expression Language supports: - Accessing local variables, method parameters, and deeply nested fields and attributes within objects. - Using comparison operators (`<`, `>`, `>=`, `<=`, `==`, `!=`, `instanceof`) to compare variables, fields, and constants in your conditions, for example: `localVar1.field1.field2 != 15`. - Using logical operators (`&&`, `||`, and `!` or `not(...)`) to build complex Boolean conditions, for example: `!isEmpty(user.email) && not(contains(user.name, "abc"))`. - Using the `null` literal (which is automatically translated to `None` in Python and `nil` in Ruby). It does **not** support: - Calling methods. Dynamic Instrumentation does not permit executing code that may have side effects. However, you can access `private` fields directly. - Arithmetic such as `i + 1`. - Other native programming language syntax beyond what is described on this page. Try [autocomplete and search (in Preview)](https://docs.datadoghq.com/dynamic_instrumentation/symdb.md) for an improved user experience using the Expression Language. ## Applications{% #applications %} Expressions can be used to produce metrics and as conditions to emit filtered data. For example, you can create a histogram from the length of a string using `len(data)` as the metric expression. Metric expressions must evaluate to a number. In Live Debugger log messages and Dynamic Instrumentation span tag values, enclose expressions in braces, for example: `User name is {user.name}`. These expressions can evaluate to any value. Instrumentation conditions must evaluate to a Boolean, for example: - `startsWith(user.name, "abc")` - `len(str) > 20` - `a == b` - `user.isActive == true` ## Contextual variables{% #contextual-variables %} The available contextual variables depend on the instrumentation location. `@return` and `@duration` are available at method exit. `@it` is used inside collection predicates. | Keyword | Description | | ------------ | ----------------------------------------------------------------------------------------------------------- | | `@return` | Provides access to the method return value. | | `@duration` | Provides access to the method call execution duration, as a floating-point value in milliseconds. | | `@exception` | Provides access to the exception thrown within the method (only available if an uncaught exception exists). | | `@it` | Provides access to the current element during collection iteration. Used in predicates for list operations. | ## General operations{% #general-operations %} The following examples assume a variable named `myString` with value `Hello, world!`: | Operation | Description | Example | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `isDefined(var)` | Checks whether a variable is defined. Returns `true` if the variable exists in the current scope, `false` otherwise. Useful for conditional logic when a variable may not be present. | {% interactive-demo for="→ isDefined(myString)" /%} | | `len(value_src)` | Gets the string length. | {% interactive-demo for="→ len(myString)" /%} | | `isEmpty(value_src)` | Checks whether the string is empty. Equivalent to `len(value_src) == 0`. | {% interactive-demo for="→ isEmpty(myString)" /%} | | `substring(value_src, startIndex, endIndex)` | Gets a substring. | {% interactive-demo for="→ substring(myString, 0, 2)" /%} | | `startsWith(value_src, string_literal)` | Checks whether a string starts with the given string literal. | {% interactive-demo for="→ startsWith(myString, \"He\")" /%} | | `endsWith(value_src, string_literal)` | Checks whether the string ends with the given string literal. | {% interactive-demo for="→ endsWith(myString, \"rdl!\")" /%} | | `contains(value_src, string_literal)` | Checks whether the string contains the string literal, or whether a collection contains an element. | {% interactive-demo for="→ contains(myString, \"ll\")" /%} | | `matches(value_src, string_literal)` | Checks whether the string matches the regular expression provided as a string literal. | {% interactive-demo for="→ matches(myString, \"^H.*!$\")" /%} | ## Collection operations{% #collection-operations %} Use `@it` in predicates over sequential collections. See the Contextual variables section for details. The following examples assume a variable named `mySequence` with value `[1,2,3,4]` and `myMap` with value `{"a": 1, "b": 2, "c": 3}`: | Operation | Description | Example | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `len(value_src)` | Gets the collection size. | {% interactive-demo for="→ len(mySequence)" /%} {% interactive-demo for="→ len(myMap)" /%} | | `isEmpty(value_src)` | Checks whether the collection is empty. Equivalent to `len(value_src) == 0`. | {% interactive-demo for="→ isEmpty(mySequence)" /%} {% interactive-demo for="→ isEmpty(myMap)" /%} | | `[ i ]`, `[ key ]` | For sequential containers returns the `i`-th item in the collection (where `i` must be an integer). For dictionaries, returns the value that corresponds to the `key` (where `key` must match the key type of the dictionary). If the item does not exist, the expression yields an error or returns null, depending on the language. | {% interactive-demo for="→ mySequence[3]" /%} {% interactive-demo for="→ myMap[\"b\"]" /%} | | `any(value_src, {predicate})` | Checks if there is at least one element in the collection that satisfies the given predicate. The current element is accessed with the `@it` reference for sequential containers. | {% interactive-demo for="→ any(mySequence, {@it > 2})" /%} | | `all(value_src, {predicate})` | Checks whether every element in a collection satisfies the specified predicate. The current element is accessed with the `@it` reference. | {% interactive-demo for="→ all(mySequence, {@it > 2})" /%} | | `filter(value_src, {predicate})` | Filters the elements of the collection using the predicate. The current element is accessed with the `@it` reference. | {% interactive-demo for="→ filter(mySequence, {@it > 1})" /%} | ## Try your own conditions{% #try-your-own-conditions %} This interactive simulator helps you experiment with the Expression Language syntax in a realistic environment. It shows how conditions affect whether data is captured when instrumenting a method. Expression support and missing-value behavior can differ in your application. Select one of the examples or enter an expression in the "when" field and click "SIMULATE" to see whether data is captured based on your condition. Available variables in this example: - `loops`: The route parameter hardcoded to `5` - `myString`: A string `"Hello, world!"` - `mySequence`: An array of integers `[1, 2, 3, 4]` - `myMap`: A dictionary `{"a": 1, "b": 2, "c": 3}` - `i`: The current loop iteration index Try these examples: **Note:** Condition evaluations and variable access patterns may vary when using the product.1112@app.route('/hello_world/')13def hello_world(loops):14myString = "hello world"15mySequence = [1, 2, 3, 4]16myMap = {"a": 1, "b": 2, "c": 3}17for i in range(loops):EmitLog ▼with templateLog on loop {i+1} generatedwhen 18pass19return "OK", 20020 curl http://example-app:80/hello_world/5