Datadog for v4 Mendix Cloud

Last update: Edit

1 Introduction

Datadog is a monitoring and analysis tool for cloud applications, providing monitoring of servers, databases, tools, and services through a SaaS-based data analytics platform. You can link your Mendix Cloud v4 apps to Datadog to provide additional monitoring.

Two types of data are provided to Datadog:

  • Data from within the Mendix app itself – this is described in Customizing the Metrics Agent, below
  • Data from the Mendix Runtime, the Java Virtual Machine (JVM), the database, and the SaaS (Software as a Service, for example Cloud Foundry) environment – this is described in Environment Metrics, below

This document explains how to configure your Mendix Cloud v4 app to send data to Datadog. If you want to know more about the capabilities of Datadog and, in particular, using Datadog with Mendix, have a look at the Mendix blog Monitor Your Mendix Apps with Datadog.

2 Datadog API Key

To make use of Datadog you will need a Datadog API key. If you already use Datadog, skip to the Existing Datadog User section to learn how to get one.

2.1 New Datadog User

If you are new to Datadog, you will need to get an account first.

  1. Go to the Datadog site (https://www.datadoghq.com/) and choose GET STARTED FREE.
  2. Enter your Datadog account details. Once you have entered your details you cannot continue until you have set up your agent.
  3. Choose the option From Source.

    The From Source option on the Agent setup screen

  4. Copy the value of DD_API_KEY key shown on the install script.

    Source install script shows DD_API_KEY=your API key

  5. You now need to use this API key with your app: see Connect Node to Datadog.

2.2 Existing Datadog User

To find your existing API key, or to request a new one for your app, do the following:

  1. Login to your Datadog account.
  2. Go to the Integrations > API screen.

    Datadog site: navigation to Integration, API

  3. Copy an existing API Key or create a new one.

    Datadog site: API Keys page

  4. For more information on Datadog API keys, see the following page on the Datadog site: How do I reset my Application Keys and related documentation.

3 Connect Node to Datadog

To send your runtime information to Datadog, you need to provide the Datadog API key to your environment.

  1. Go to the Environments page of your app in the Developer Portal.
  2. Click Details to select the environment you wish to monitor with Datadog.
  3. Open the Runtime tab.
  4. Add a Custom Environment Variable.
  5. Select DD_API_KEY from the Name dropdown.

    Dropdown containing custom environment variable names

  6. Enter the Datadog API key, obtained in the Datadog API Key section, above, as the Value of the Environment Variable.

  7. Add a second Custom Environment Variable:

    • Name: DD_LOG_LEVEL
    • Value: INFO

    This will ensure that some messages are sent to Datadog. You can change the log level later once you have confirmed that Datadog is receiving them.

  8. Return to the Environments page for your app and Deploy or Transport your app into the selected environment.

  9. Restart the application.

4 Tagging Metrics for Datadog

To identify the metrics for your app and environment in Datadog, it is recommended that you add tags for the app name and environment. Our recommendation is that you use the following tags:

  • app:{app_name} – this enables you to identify all metrics sent from your app (for example, app:customermanagement)
  • env:{environment_name} – this enables you to identify metrics sent from a particular environment so you can separate out production metrics from test metrics (for example, env:accp)

To set these tags, do the following:

  1. Go to the Environments page of your app in the Developer Portal.
  2. Click Details to select an environment you are monitoring with Datadog.
  3. Open the Tags tab.
  4. Add a Tag – this is the string which is sent to Datadog as a tag. Example metric showing tags in Datadog
  5. Restart the application.

Setting these values for your app means that all metrics from this environment of your app will have these tags. For example, the tags for mx.microflow.time.avg for this set of metrics include app:customermanagement and env:accp.

Example metric showing tags in Datadog

You can add more tags if you want, but note that Datadog’s charges include an element for custom metrics as described on the Datadog site.

5 Customizing the Metrics Agent

Mendix provides logging of various activities within the app. These are sent to Datadog with the namespace mx.

By default, Mendix will pass a log of all request handler activity to Datadog and no other information. However, by using JSON to configure the metrics agent, you can add logs of microflows and activities within microflows, and restrict which request handler calls are sent.

5.1 Format of Metrics Agent Configuration

You can specify which request handlers, microflows, and activities are reported to Datadog using a JSON configuration with the following format (note that this is the syntax and not an example of this custom setting):

{
  "requestHandlers": [
    {
      "name": "*" | "<requesthandler>"
    }
  ],
  "microflows": [
    {
      "name": "*" | "<microflow>"
    }
  ],
  "activities": [
    {
      "name": "*" | "<activity>"
    }
  ]
}
Value What Is Sent Note
"name": "*" All Default
"name": "<requesthandler>" All request handler calls of this type click Request Handlers1 below to see the list of options
"name": "<microflow>" Each time this microflow is run The format is <module>.<microflow>
For example, TrainingManagement.ACT_CancelScheduledCourse
"name": "<activity>" All activities of this type click Activities2 below to see the list of options

[1]Request Handlers (click to see list)

The following Mendix request handler calls will be passed to Datadog:

  • WebserviceRequestHandler
  • ServiceRequestHandler – OData requests
  • RestRequestHandler
  • ProcessorRequestHandler
  • ClientRequestHandler
  • FileRequestHandler
  • PageUrlRequestHandler

[2]Activities (click to see list)

The following Mendix activities can be passed to Datadog:

  • CastObject
  • ChangeObject
  • CommitObject
  • CreateObject
  • DeleteObject
  • RetrieveObject
  • RollbackObject
  • AggregateList
  • ChangeList
  • ListOperation
  • JavaAction
  • Microflow
  • CallRestService
  • CallWebService
  • ImportWithMapping
  • ExportWithMapping

Example

The following example will send logs for:

  • All request handlers
  • The microflow After_Startup in the module Administration
  • The CreateObject and DeleteObject activities
{
  "requestHandlers": [
    {
      "name": "*"
    }
  ],
  "microflows": [
    {
      "name": "Administration.After_Startup"
    }
  ],
  "activities": [
    {
      "name": "CreateObject"
    },
    {
      "name": "DeleteObject"
    }
  ]
}

5.2 Passing a Configuration to the Metrics Agent

You pass the configuration to the metrics agent by adding a Custom Runtime Setting to your Mendix Cloud environment.

  1. Go to the Environments page of your app.
  2. Click Details next to the environment you have configured for Datadog.
  3. Add a Custom Environment Variable METRICS_AGENT_CONFIG with the value of the JSON required for your configuration.

  4. Click Save.

  5. Restart your app to apply the new settings.

6 Environment Metrics

As well as information from within the Mendix app (identified by the namespace mx), your app environment will also provide metrics in the following namespaces:

  • database – metrics on the database performance
  • datadog – metrics on datadog usage
  • jmx – metrics from the Mendix runtime
  • jvm – metrics from the Java virtual machine in which the Mendix runtime runs
  • postgresql – database metrics specific to PostgreSQL databases
  • synthetics – metrics specifically labelled as coming from tests (see the Datadog documentation Synthetics)
  • system – metrics from the base system running on the platform or PaaS (see the Datadog documentation System Check)

6.1 Useful Metrics for Mendix Apps

The following metrics are useful when monitoring the performance of your Mendix app:

  • database.diskstorage_size
  • jvm.heap_memory
  • jvm.heap_memory_committed
  • jvm.heap_memory_init
  • jvm.heap_memory_max
  • jvm.non_heap_memory
  • jvm.non_heap_memory_committed
  • jvm.non_heap_memory_init
  • jvm.non_heap_memory_max
  • postgresql.connections
  • postgresql.database_size
  • postgresql.max_connections
  • postgresql.percent_usage_connections

Note that the absolute values are often not useful, but looking at trends over time can indicate performance issues or future action which might be required. Some of these trends are similar to those described in Trends in Mendix Cloud v4.

7 Additional Information

7.1 Log Levels

The valid values for DD_LOG_LEVEL are:

  • CRITICAL
  • ERROR
  • WARNING
  • INFO
  • DEBUG

7.2 Datadog Events Log

The Datadog Events log contains events which come from your app: those are the same events that would appear in the Mendix Console. It does not contain events from the environment.

Example events log

7.3 Datadog Agent not Started

If you configure your app for Datadog but the Datadog agent is not started, the events will be sent to the app log files.

7.4 Datadog Issues

If you have any issues related to accessing Datadog, please contact their support here: Support | Datadog, or by email at support@datadoghq.com.

8 Read More