Skip to content

feat(opentelemetry): add metrics/logs/traces support to OTel #11306

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.

Sign up for GitHub

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

Open
msvolenski wants to merge 1 commit into
base: development
Choose a base branch
from
Open

feat(opentelemetry): add metrics/logs/traces support to OTel #11306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 3 additions & 1 deletion content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ description: "How to use an APM (application performance monitoring) tool to mon

There are several application performance monitoring (APM) tools for cloud applications available through a software as a service (SaaS) based data analytics platform. These APM tools provide comprehensive monitoring of servers, databases, tools, and services.

Mendix provides out-of-the-box configuration to use Datadog, AppDynamics, Dynatrace, Splunk Cloud Platform, and New Relic to provide additional monitoring for your Mendix Apps running on Mendix Cloud.
Mendix provides out-of-the-box configuration to use Datadog, AppDynamics, Dynatrace, Splunk Cloud Platform, New Relic, and OpenTelemetry to provide additional monitoring for your Mendix Apps running on Mendix Cloud.

The table below summarizes the monitoring capabilities each tool supports:

Expand All @@ -21,6 +21,7 @@ The table below summarizes the monitoring capabilities each tool supports:
| [Datadog](https://www.datadoghq.com/) | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="checkmark-circle-filled" color="green" >}} | 7.15 ¹ |
| [Splunk Cloud Platform](https://www.splunk.com/en_us/products/splunk-cloud-platform.html) | {{< icon name="checkmark-circle-filled" color="green" >}} |{{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="remove-circle-filled" color="red" >}} | 9.7 |
| [New Relic](https://www.newrelic.com/) | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="remove-circle-filled" color="red" >}} | 9.7 |
| [OpenTelemetry](https://opentelemetry.io/) | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="checkmark-circle-filled" color="green" >}} | {{< icon name="checkmark-circle-filled" color="green" >}} | 10.24.12, 11.5 |

<small>¹ Logs and metrics are available from Mendix 7.15 and above. Tracing requires Mendix 10.24.12 or 11.5 and above.</small>

Expand All @@ -31,6 +32,7 @@ For details on how to add a specific APM tool to your app, see one of the follow
* [AppDynamics for Mendix Cloud](/developerportal/operate/appdynamics-metrics/)
* [Datadog for Mendix Cloud](/developerportal/operate/datadog-metrics/)
* [Dynatrace for Mendix Cloud](/developerportal/operate/dynatrace-metrics/)
* [OpenTelemetry for Mendix Cloud](/developerportal/operate/opentelemetry/)
* [Splunk for Mendix Cloud](/developerportal/operate/splunk-metrics/)
* [New Relic for Mendix Cloud](/developerportal/operate/newrelic-metrics/)

Expand Down
161 changes: 161 additions & 0 deletions ...ent/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
---
title: "OpenTelemetry for Mendix Cloud"
url: /developerportal/operate/opentelemetry/
weight: 15
description: "How to configure Mendix Cloud to send traces, metrics, and logs to an OpenTelemetry-compatible observability backend."

Check failure on line 5 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 5, "column": 124}}}, "severity": "ERROR"}
---

## Introduction

Mendix Cloud supports sending telemetry — traces, metrics, and logs — directly to any [OpenTelemetry](https://opentelemetry.io/) Protocol (OTLP)-compatible observability backend, such as Grafana Cloud.

Check failure on line 10 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 10, "column": 171}}}, "severity": "ERROR"}

Check failure on line 10 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro, use an en dash (–) instead.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 10, "column": 68}}}, "severity": "ERROR"}

Check failure on line 10 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro, use an en dash (–) instead.

Raw Output:
{"message": "[Mendix.Dashes] Remove spaces around the em dash (—). Or, to set off a list item intro, use an en dash (–) instead.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 10, "column": 40}}}, "severity": "ERROR"}

When enabled, the Mendix operator automatically injects an OpenTelemetry Collector sidecar container alongside your application. This sidecar receives telemetry from the Mendix Runtime and forwards it to your chosen backend. No manual installation of the collector is required.

Check failure on line 12 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 12, "column": 217}}}, "severity": "ERROR"}

For more information about what metrics and data Mendix provides, see [Monitoring Your Mendix Apps with an APM Tool](/developerportal/operate/monitoring-with-apm/).

{{% alert color="info" %}}
The OpenTelemetry integration requires Mendix Runtime **10.24.12** or above, or **11.5** or above.
{{% /alert %}}

## Prerequisites

This integration exclusively supports destinations that ingest telemetry via standard core exporters. Compatible backends include any vendor or platform that natively accepts inbound OTLP (via gRPC or HTTP) or Prometheus Remote Write (prometheusremotewrite) streams. Custom, proprietary vendor SDK exporters are not supported.

Before connecting your app to an OpenTelemetry backend, ensure you have:

Check failure on line 24 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 24, "column": 48}}}, "severity": "ERROR"}

* Access to an OTLP-compatible observability backend (for example, Grafana Cloud)

Check failure on line 26 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 26, "column": 46}}}, "severity": "ERROR"}
Comment thread
msvolenski marked this conversation as resolved.
* The OTLP ingestion endpoint URL for your backend

Check failure on line 27 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 27, "column": 44}}}, "severity": "ERROR"}
* An API token or other credentials for authenticating with the backend

Check failure on line 28 in content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "content/en/docs/deployment/mendix-cloud-deploy/monitoring-with-apm/opentelemetry.md", "range": {"start": {"line": 28, "column": 65}}}, "severity": "ERROR"}
* A licensed Mendix Cloud app

## Connecting Your Node to an OpenTelemetry Backend{#connect-node}

To connect your Mendix Cloud environment to an OpenTelemetry backend:

1. Open the [Developer Portal](https://sprintr.home.mendix.com/).
2. Select your app and navigate to **Environments**.
3. Click **Details** for the environment you want to configure.
4. Go to the **Environment Variables** tab.
5. Add the following environment variables:

| Variable | Description | Default |
|---|---|---|
| `MX_OTEL_ENABLED` | Master switch. Set to `true` to enable the integration. | `false` |
| `MX_OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP ingestion URL for all signals (traces, metrics, and logs). | — |
| `MX_OTEL_EXPORTER_OTLP_HEADERS` | HTTP headers sent with every request. Used for authentication. Format: `key1=value1,key2=value2`. | — |
| `MX_OTEL_EXPORTER_OTLP_PROTOCOL` | Transport protocol. One of `grpc`, `http/protobuf`, or `http/json`. | `http/protobuf` |

6. Optionally, set service identity variables to control how your app appears in your observability backend (see [Service Identity](#service-identity)).
7. Click **Save**.

{{% alert color="warning" %}}
You need to redeploy your app, not just restart it, for the OpenTelemetry integration to take effect. The sidecar is injected at deploy time.
{{% /alert %}}

### Example — Grafana Cloud

Grafana Cloud exposes a single OTLP endpoint for all signals over HTTPS. To connect your app:

1. In your Grafana Cloud stack, navigate to **Getting Started guide** -> **OpenTelemetry** > **Serverless/Other**.
2. Create an access policy token with `metrics:write`, `logs:write`, and `traces:write` scopes.
3. Copy the OTLP endpoint URL and your token.
4. Set the following environment variables on your Mendix environment:

```
MX_OTEL_ENABLED=true
MX_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-eu-west-0.grafana.net/otlp
MX_OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic BASE64_ENCODED_INSTANCE_ID:TOKEN
MX_OTEL_SERVICE_NAME=my-mendix-app # only necessary if you want to override the default service name (app subdomain)
MX_OTEL_DEPLOYMENT_ENV=production # only necessary if you want to set the deployment environment (defaults to `none`) or can be set via the `env` application tag
```

Replace `BASE64_ENCODED_INSTANCE_ID:TOKEN` with the base64 encoding of `<instance-id>:<token>` as shown on the Grafana Cloud OTLP configuration page.
Comment thread
msvolenski marked this conversation as resolved.

5. Redeploy your app.

Within a minute of the first request to your app, traces should appear in Grafana Cloud's **Explore** view, and metrics should be visible in Prometheus datasource queries.

## Additional Information{#additional-info}

### Per-Signal Configuration{#per-signal}

By default, all three signals — traces, metrics, and logs — are sent to the backend configured with `MX_OTEL_EXPORTER_OTLP_ENDPOINT`. You can control each signal independently using the following variables:

| Variable | Default | Valid values |
|---|---|---|
| `MX_OTEL_TRACES_EXPORTER` | _(inferred)_ | `otlp`, `none` |
| `MX_OTEL_METRICS_EXPORTER` | _(inferred)_ | `otlp`, `prometheusremotewrite`, `none` |
| `MX_OTEL_LOGS_EXPORTER` | _(inferred)_ | `otlp`, `none` |

When not set explicitly, the exporter for each signal is inferred from the endpoint variables that are present. Setting a signal to `none` disables it — the sidecar accepts the data from the Runtime but discards it without forwarding.

### Per-Signal OTLP Overrides

If your backend requires different endpoints, headers, or protocols per signal, you can override the base OTLP configuration for each signal individually:

| Base variable | Traces override | Metrics override | Logs override |
|---|---|---|---|
| `MX_OTEL_EXPORTER_OTLP_ENDPOINT` | `MX_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `MX_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `MX_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` |
| `MX_OTEL_EXPORTER_OTLP_HEADERS` | `MX_OTEL_EXPORTER_OTLP_TRACES_HEADERS` | `MX_OTEL_EXPORTER_OTLP_METRICS_HEADERS` | `MX_OTEL_EXPORTER_OTLP_LOGS_HEADERS` |
| `MX_OTEL_EXPORTER_OTLP_PROTOCOL` | `MX_OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | `MX_OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | `MX_OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` |

{{% alert color="info" %}}
Per-signal headers **fully replace** the base headers — they do not merge. If you set `MX_OTEL_EXPORTER_OTLP_TRACES_HEADERS`, the value of `MX_OTEL_EXPORTER_OTLP_HEADERS` is ignored for traces.
{{% /alert %}}

### Log Redaction{#log-redaction}

Email addresses are automatically redacted from log entries before they are sent to your backend. To disable this redaction, set `LOGS_REDACTION` to `false`. By default, this variable is set to `true`.

| Variable | Default | Description |
|---|---|---|
| `LOGS_REDACTION` | `true` | When `true`, email addresses are redacted from log entries before export. Set to `false` to disable email redaction. |

In addition, certain secret patterns — such as database connection strings and storage endpoint URLs logged by the Mendix Runtime — are always redacted regardless of this setting and cannot be disabled.

### Prometheus Remote Write (Metrics Only){#prometheus-remote-write}

If your metrics backend uses Prometheus Remote Write (for example, Grafana Mimir, Thanos, or VictoriaMetrics), you can send metrics via PRW while still sending traces and logs via OTLP.

| Variable | Default | Description |
|---|---|---|
| `MX_OTEL_EXPORTER_PROMETHEUSREMOTEWRITE_ENDPOINT` | — | Remote Write URL (for example, `https://mimir.example.com/api/v1/push`). When set and no OTLP endpoint covers metrics, the PRW exporter is selected automatically — you do not need to set `MX_OTEL_METRICS_EXPORTER=prometheusremotewrite` explicitly. |
| `MX_OTEL_EXPORTER_PROMETHEUSREMOTEWRITE_HEADERS` | — | HTTP headers for the PRW endpoint. Format: `key1=value1,key2=value2`. |

OTel resource attributes (service name, version, environment, and custom tags) are automatically converted to Prometheus labels when using this exporter.

**Example — metrics to a PRW endpoint, traces and logs via OTLP:**

```
MX_OTEL_ENABLED=true

# Traces and logs via OTLP
MX_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com
MX_OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer YOUR_OTLP_TOKEN

# Metrics via Prometheus Remote Write (takes precedence over OTLP for metrics)
MX_OTEL_METRICS_EXPORTER=prometheusremotewrite
MX_OTEL_EXPORTER_PROMETHEUSREMOTEWRITE_ENDPOINT=https://mimir.example.com/api/v1/push
MX_OTEL_EXPORTER_PROMETHEUSREMOTEWRITE_HEADERS=Authorization=Bearer YOUR_MIMIR_TOKEN

MX_OTEL_SERVICE_NAME=my-mendix-app
```

### Service Identity{#service-identity}

These variables control the resource attributes attached to all telemetry. They determine how your app is identified in your observability backend.

| Variable | Default | Description |
|---|---|---|
| `MX_OTEL_SERVICE_NAME` | App subdomain | Service name (`service.name` attribute). Defaults to the subdomain of the app's first route (for example, `my-app` from `my-app.mendixcloud.com`). Set this variable to override it. |
| `MX_OTEL_SERVICE_VERSION` | Model version | Service version (`service.version` attribute). Defaults to the Mendix model version. Falls back to the `version` application tag if set, then `unversioned`. |
| `MX_OTEL_DEPLOYMENT_ENV` | `env` tag or `none` | Deployment environment (`deployment.environment.name` attribute). Defaults to the `env` application tag if set, otherwise `none`. |
| `MX_OTEL_RESOURCE_ATTRIBUTES` | _(from app tags)_ | Additional resource attributes as comma-separated `key=value` pairs. Automatically populated from the application tags set in the Developer Portal. Can be set directly to override the tag-derived value. |

### OpenTelemetry Issues

If you encounter issues with the OpenTelemetry integration that are not caused by your backend configuration, submit a support request through the [Mendix Support Portal](https://support.mendix.com/).

## Read More

* [Metrics — Mendix Runtime](/refguide/metrics/)
Loading