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

Update tracing documentation to use the Java agent #8939

Open
wants to merge 6 commits into
base: development
Choose a base branch
from
Open
Changes from 4 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
41 changes: 31 additions & 10 deletions content/en/docs/refguide/runtime/tracing-in-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,33 +25,54 @@ In Mendix 10.18.0 and above, the runtime generates spans for:

## Configuration

### Minimal configuration
Since Mendix 10.19.0,

The minimal configuration to enable tracing is:
### Minimal Configuration {#min-configuration}

#### Mendix 10.19.0 and Above

In Mendix 10.19 and above, tracing configuration is handled through the [OpenTelemetry Java Agent](https://opentelemetry.io/docs/zero-code/java/agent/). Use the following steps to set up a minimal tracing configuration:

1. Download [opentelemetry-javaagent.jar](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar) from the [OpenTelemetry Java Instrumentation release page](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases) and save it to a location where your Mendix app can access it.
1. In the [Server settings](/refguide/configuration/#server) of Studio Pro, locate the field **Extra JVM parameters** and add the following:

```
-javaagent:{/path/to/opentelemetry-javaagent.jar} -Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-api.enabled=true -Dotel.service.name="{My App}"
```

1. Change `{/path/to/opentelemetry-javaagent.jar}` to the location where you stored the agent earlier and `{My App}` to the name under which you want your traces to appear.

This will enable Mendix related tracing, while silencing the tracing of internals. The traces will be sent to http://localhost:4317.
MarkvanMents marked this conversation as resolved.
Show resolved Hide resolved

#### Mendix 10.18 MTS

In Mendix 10.18, the minimal configuration to enable tracing is:

* Set the `OpenTelemetry.Enabled` [runtime setting](/refguide/custom-settings/) to `true`
* Set the `otel.service.name` runtime setting to a service name

This will enable tracing. The traces will be sent to http://localhost:4317.
This will enable tracing. The traces will be sent to http://localhost:4317.
MarkvanMents marked this conversation as resolved.
Show resolved Hide resolved

### Testing

To test you can use [Jaeger](https://www.jaegertracing.io/), for example the all-in-one binary or docker image. Jaeger will listen to the above endpoint by default.
To test the tracing you can use [Jaeger](https://www.jaegertracing.io/). For example, the all-in-one binary or docker image. Jaeger will listen to the above endpoint by default.

Alternatively you can set up the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/), which will also listen to the default endpoint and can be configured to send to backends which support OpenTelemetry. Check with your APM vendor to confirm that OpenTelemetry is supported. The free online collector configuration tool [OTelBin](https://github.com/dash0hq/otelbin) can help with collector configuration.

### All settings

Below we list the supported tracing-related runtime settings. See [Configure the SDK](https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties) for a reference on the settings that are prefixed with `otel.`.
Below we list the ones that are supported by the Mendix runtime. See [Configure the SDK](https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties) for a reference on the settings that are prefixed with `otel,`.
MarkvanMents marked this conversation as resolved.
Show resolved Hide resolved

In Mendix 10.19.0 and above, the Java Agent can be configured through system properties, which can be added to the **Extra JVM parameters** field (for example, `-Dotel.exporter.otlp.traces.endpoint`), or set through environment variables.

| Name | Description | Default |
|------|-------------|---------|
| `OpenTelemetry.Enabled` | Can be set to `true` or `false` in order to disable or enable tracing.<br/> {{% alert color="info" %}} We support dynamically enabling/disabling tracing using this setting, but the other settings will only be applied the first time you enable tracing.{{% /alert %}} | `false` |
| `otel.service.name` | The name of the service. | `unknown_service:java` |
| `otel.resource.attributes` | The resource attributes to include in every span. Example: `attribute1=value1,attribute2=value2` | |
| `otel.service.name` | The name of the service. | `runtimelauncher` *(In Mendix 10.18 `unknown_service:java`)* |
| `otel.resource.attributes` | Extra resource attributes to include in every span. Example: `attribute1=value1,attribute2=value2` | |
| `otel.traces.exporter` | Comma-separated list of span exporters. Supported values are: `otlp`, `console`, `logging-otlp`, and `none`. | `otlp` |
| `otel.exporter.otlp.traces.protocol` | The transport protocol to use on OTLP trace requests. Options include `grpc` and `http/protobuf`. | `grpc` |
| `otel.exporter.otlp.traces.endpoint` | The endpoint to send all OTLP traces to. It must be a URL with a scheme of either http or https based on the use of TLS. | `http://localhost:4317` when the protocol is `grpc`<br>`http://localhost:4318` when the protocol is `http/protobuf` |
| `otel.exporter.otlp.traces.certificate` | The path to the file containing trusted certificates to use when verifying a trace server's TLS credentials. The file should contain one or more X.509 certificates in PEM format. | By default the host platform's trusted root certificates are used. |
| `otel.exporter.otlp.traces.client.key` | The path to the file containing the private client key to use when verifying a trace client's TLS credentials. The file should contain one private key in PKCS8 PEM format. | By default no client key file is used. |
| `otel.exporter.otlp.traces.client.certificate` | The path to the file containing trusted certificates to use when verifying a trace client's TLS credentials. The file should contain one or more X.509 certificates in PEM format. | By default no certificate file is used. |

In addition to the above settings, additional settings for OpenTelemetry can be passed as environment variables or system properties. We do not explicitly support these settings, but they will all be passed to the OpenTelemetry system in the runtime. [See here for a list of all OpenTelemetry settings.](https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties)
| `OpenTelemetry.Enabled` *(Mendix 10.18 only)*| Can be set to `true` or `false` in order to disable or enable tracing. | `false` |