From 5b40e7a839c0bf0e828cb4b778e989e3606bf571 Mon Sep 17 00:00:00 2001 From: Leroy van Engelen Date: Mon, 20 Jan 2025 14:54:40 +0100 Subject: [PATCH 1/6] Update documentation for using the Java agent --- .../refguide/runtime/tracing-in-runtime.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index acfb0972f8c..8f3efb8bffb 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -25,14 +25,19 @@ In Mendix 10.18.0 and above, the runtime generates spans for: ## Configuration -### Minimal configuration +Since Mendix 10.19.0, tracing configuration is handled through the [OpenTelemetry Java Agent](https://opentelemetry.io/docs/zero-code/java/agent/). -The minimal configuration to enable tracing is: +### Minimal configuration -* Set the `OpenTelemetry.Enabled` [runtime setting](/refguide/custom-settings/) to `true` -* Set the `otel.service.name` runtime setting to a service name +Follow these steps for a minimal tracing configuration: +* Download [opentelemetry-javaagent.jar](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar) from the OpenTelemetry Java Agent Release page and save it to a location where your Mendix app can access it. +* In the [Server settings](https://docs.mendix.com/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" + ``` + Please 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 tracing. The traces will be sent to http://localhost:4317. +This will enable Mendix related tracing, while silencing tracing of internals. The traces will be sent to http://localhost:4317. 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. @@ -40,18 +45,15 @@ Alternatively you can set up the [OpenTelemetry collector](https://opentelemetry ### 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.`. +The Java Agent can be configured through system properties, which can be added to the **Extra JVM parameters** field (e.g. `-Dotel.exporter.otlp.traces.endpoint`), or environment variables. 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. | Name | Description | Default | |------|-------------|---------| -| `OpenTelemetry.Enabled` | Can be set to `true` or `false` in order to disable or enable tracing.
{{% 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` | +| `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`
`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) From f2207d2fc0b76cfe7bed4650ce8baa2e55adcb2e Mon Sep 17 00:00:00 2001 From: Maria Shaposhnikova <38249778+MariaShaposhnikova@users.noreply.github.com> Date: Tue, 21 Jan 2025 17:09:15 +0100 Subject: [PATCH 2/6] Add an anchor for RN --- content/en/docs/refguide/runtime/tracing-in-runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index 8f3efb8bffb..a08299050e6 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -27,7 +27,7 @@ In Mendix 10.18.0 and above, the runtime generates spans for: Since Mendix 10.19.0, tracing configuration is handled through the [OpenTelemetry Java Agent](https://opentelemetry.io/docs/zero-code/java/agent/). -### Minimal configuration +### Minimal Configuration {#min-configuration} Follow these steps for a minimal tracing configuration: * Download [opentelemetry-javaagent.jar](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar) from the OpenTelemetry Java Agent Release page and save it to a location where your Mendix app can access it. From 39a37b4825fe31a5aba4fd99e58b990a7261687b Mon Sep 17 00:00:00 2001 From: Mark van Ments Date: Wed, 22 Jan 2025 14:12:46 +0100 Subject: [PATCH 3/6] Proofread and put back 10.18 instructions --- .../refguide/runtime/tracing-in-runtime.md | 41 ++++++++++++++----- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index a08299050e6..75d0b568609 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -25,27 +25,45 @@ In Mendix 10.18.0 and above, the runtime generates spans for: ## Configuration -Since Mendix 10.19.0, tracing configuration is handled through the [OpenTelemetry Java Agent](https://opentelemetry.io/docs/zero-code/java/agent/). +Since Mendix 10.19.0, ### Minimal Configuration {#min-configuration} -Follow these steps for a minimal tracing configuration: -* Download [opentelemetry-javaagent.jar](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar) from the OpenTelemetry Java Agent Release page and save it to a location where your Mendix app can access it. -* In the [Server settings](https://docs.mendix.com/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" - ``` - Please 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. +#### Mendix 10.19.0 and Above -This will enable Mendix related tracing, while silencing tracing of internals. The traces will be sent to http://localhost:4317. +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: -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. +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. + +#### 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. + +### Testing + +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 -The Java Agent can be configured through system properties, which can be added to the **Extra JVM parameters** field (e.g. `-Dotel.exporter.otlp.traces.endpoint`), or environment variables. 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. +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,`. + +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 | |------|-------------|---------| @@ -57,3 +75,4 @@ The Java Agent can be configured through system properties, which can be added t | `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. | +| `OpenTelemetry.Enabled` *(Mendix 10.18 only)*| Can be set to `true` or `false` in order to disable or enable tracing.
{{% 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` | From 81822134e726b18151b0ad3c5b5de1effbede882 Mon Sep 17 00:00:00 2001 From: Mark van Ments Date: Wed, 22 Jan 2025 14:17:10 +0100 Subject: [PATCH 4/6] Proofread --- content/en/docs/refguide/runtime/tracing-in-runtime.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index 75d0b568609..3cdb454221d 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -67,7 +67,7 @@ In Mendix 10.19.0 and above, the Java Agent can be configured through system pro | Name | Description | Default | |------|-------------|---------| -| `otel.service.name` | The name of the service. | `runtimelauncher` | +| `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` | @@ -75,4 +75,4 @@ In Mendix 10.19.0 and above, the Java Agent can be configured through system pro | `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. | -| `OpenTelemetry.Enabled` *(Mendix 10.18 only)*| Can be set to `true` or `false` in order to disable or enable tracing.
{{% 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` | +| `OpenTelemetry.Enabled` *(Mendix 10.18 only)*| Can be set to `true` or `false` in order to disable or enable tracing. | `false` | From f414fa9c113613e0da90a9714a89cb4b6107bedd Mon Sep 17 00:00:00 2001 From: Mark van Ments Date: Wed, 22 Jan 2025 14:23:08 +0100 Subject: [PATCH 5/6] Proofread --- content/en/docs/refguide/runtime/tracing-in-runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index 3cdb454221d..e0a304efd0e 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -44,7 +44,7 @@ In Mendix 10.19 and above, tracing configuration is handled through the [OpenTel This will enable Mendix related tracing, while silencing the tracing of internals. The traces will be sent to http://localhost:4317. -#### Mendix 10.18 MTS +#### Mendix 10.18 In Mendix 10.18, the minimal configuration to enable tracing is: From cf1eeeb9d29d5e9765d04da6fea3d73b66bff5c7 Mon Sep 17 00:00:00 2001 From: Mark van Ments Date: Thu, 23 Jan 2025 15:38:37 +0100 Subject: [PATCH 6/6] Respond to review. --- content/en/docs/refguide/runtime/tracing-in-runtime.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/refguide/runtime/tracing-in-runtime.md b/content/en/docs/refguide/runtime/tracing-in-runtime.md index e0a304efd0e..39dfc49c2ac 100644 --- a/content/en/docs/refguide/runtime/tracing-in-runtime.md +++ b/content/en/docs/refguide/runtime/tracing-in-runtime.md @@ -42,7 +42,7 @@ In Mendix 10.19 and above, tracing configuration is handled through the [OpenTel 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. +This will enable Mendix related tracing, while silencing the tracing of internals. The traces will be sent to http://localhost:4317. #### Mendix 10.18 @@ -51,7 +51,7 @@ 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. ### Testing @@ -61,7 +61,7 @@ Alternatively you can set up the [OpenTelemetry collector](https://opentelemetry ### All settings -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,`. +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.`. 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.