This is documentation for the next version of Grafana Beyla documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Beylabreadcrumb arrow Configurebreadcrumb arrow Language specific agents
Open source

Language specific agents

Certain programming languages that Beyla instruments are using managed runtimes with complicated threading models, such that Beyla cannot perform correct thread context propagation solely by using eBPF based techniques. In certain situations, for example Java, capturing TLS traffic is also not possible by eBPF techniques, because the Java SDK has its own TLS implementation written in Java. A lot of these programming languages start program execution with interpreters, but later perform method or execution trace compilation using Just-In-Time(JIT) compilers, which generate code in anonymous memory regions. These anonymous regions cannot be attached to with eBPF uprobes, because there is no Linux inode number associated with them. Therefore, it’s not possible to perform eBPF instrumentation on the generated code, without potentially unstable techniques of stopping the program with ptrace and remapping the anonymous regions to memory mapped files.

Because of the inherent limitation of certain programming languages and technologies, Beyla dynamically injects tiny language specific agents for certain languages, to be able to perform TLS traffic capture and context propagation. Currently, Beyla uses language agents for Java and NodeJS.

YAML section: nodejs

YAML option

Environment variable

DescriptionTypeDefault
enabled

BEYLA_NODEJS_ENABLED

Inject the Node.js agent for context propagation, runtime metrics, and manual spans.booleantrue
manual_spans

BEYLA_NODEJS_MANUAL_SPANS

Capture spans created through the OpenTelemetry API when no SDK is registered. Requires agent injection and Node.js 14 or later.booleanfalse

Beyla injects the Node.js agent through the inspector interface. It connects to 127.0.0.1:9229, opening the inspector with SIGUSR1 when necessary. Before sending the signal, Beyla checks whether it would stop the process or invoke a custom handler. If so, it skips that injection path. Set enabled to false if your application uses that signal.

Node.js uses libssl for TLS traffic, which Beyla captures with eBPF. The agent provides context propagation and runtime metrics. Disabling injection also disables those agent features.

Set manual_spans to true to capture spans that the application creates with the OpenTelemetry API before registering an SDK:

YAML 
nodejs:
  enabled: true
  manual_spans: true

The manual-span bridge requires Node.js 14 or later. Enabling it on an older runtime causes Beyla to skip the entire Node.js agent, including context propagation and runtime metric collection. The bridge stays inactive when an SDK is already registered. If the application registers an SDK later, the bridge yields to it.

YAML section: javaagent

YAML option

Environment variable

DescriptionTypeDefault
enabled

BEYLA_JAVAAGENT_ENABLED

Enable dynamic injection of the Java agent.boolean(true)
attach_timeout

BEYLA_JAVAAGENT_ATTACH_TIMEOUT

Timeout for waiting on dynamic attach to succeed.string“10s”

The Java agent provides context propagation, TLS traffic capture, and JVM class, thread, CPU, and GC duration metrics. Disabling it leaves HotSpot USDT memory metrics available. The dynamic injection of the agent is supported for OpenJDK Hotspot JVM (and derivatives) and for OpenJ9. Minimum Java version supported is Java 8. If the JVM is busy during the agent attach process, the attach process may take longer than 10 seconds. You can use the attach_timeout option to increase the time Beyla waits for the dynamic attach to successfully complete.

Injection of the Java agent requires that the target process has writeable file system, for example, the injection process doesn’t work for containers with read-only file systems.