Logging with Datadog
Logging is a critical piece in any digital system. It enhances visibility, facilitates troubleshooting, and supports system reliability. With this recipe, you can implement a solution with Conscia that sends log entries to Datadog.
Overall Orchestration Flow
Clients that invoke this orchestration flow can pass a logging message and log status (INFO, WARN, ERROR) to Datadog over HTTP.
In general, generic Components such as logging should not establish dependencies. Therefore, a common pattern is for a component that has something to log to use the logging component as a Sub Component.
Mapping Out DX Engine Elements
This flow consists of three DX Engine elements:
- Datadog Connection (
datadog-connection
): A DX Engine Connection to Datadog. - Datadog API Key (
datadog-api-key
): A Secret to store the Datadog token used by that Connection. - Datadog Logger (
datadog-log
): An Orchestration Component that uses that Connection to log messages to Datadog.
DX Engine Configuration Details
We can store the Datadog token as a secret in the DX Engine. To create the secret, in the Conscia UI:
- Click Settings in the top-nav, and then select Secrets.
- Click Add Secret.
- Set Secret Code to a value such as datadog-api-key.
- Set Secret Name to a value such as Datadog API Key.
- Set Secret Value to
{Your Datadog token}
. - Optionally, enter a Description for the secret.
- Click Submit.
To create the Datadog Connection, in the Conscia UI:
- Click Settings in the top-nav, and then select Connections.
- Click Add Connection.
- Set Connection Code to a value such as datadog-connection.
- Set Connection Name to a value such as Datadog Connection.
- Optionally, enter a Connection Description for the connection.
- Select the Universal API Connector.
- Click Submit.
To configure the Datadog Connection, in the Conscia UI:
- Click the Edit button for the Datadog Logging Connection.
- Under Base URL, for Get value from, select Literal.
- Set the value of Base URL to the Datadog API base URL, such as
https://http-intake.logs.{your-region}.datadoghq.com/api/v2/logs
, replacing{your-region}
with your Datadog server region. - Under Base Headers, click Add another item.
- For the new header, set Header to DD-API-KEY.
- For the new header, set Value to Secret.
- For the value of the new header, select the secret created previously, such as Datadog API Key.
- Under Base Headers, click Add another item.
- For the new header, set Header to Content-Type.
- For the new header, set Value to Literal.
- For the value of the new header, enter
application/json
. - Under Base Headers, click Add another item.
- For the new header, set Header to Accept.
- For the new header, set Value to Literal.
- For the value of the new header, enter
application/json
. - Click Submit.
To create the Datadog Logger Orchestration Component, in the Conscia DX UI:
- In the top navigation, click Manage Experiences, and then click Components. The Manage Components page appears.
- Click Add Component. The Create Component wizard appears.
- For Component Code, enter an identifier for the component, such as datadog-log.
- For Name, enter a name for the component, such as Datadog Logger.
- Optionally, enter a Component Description.
- Select the No Rules checkbox. Experience Rules are not relevant to this Component.
- For Component Type, select Conscia - Universal API Connector. This Component Type can connect to almost any Webservice API.
- Optionally, select the Is Asynchronous checkbox.
- Click Submit.
The advantage of selecting Is Asynchronous is that the orchestration flow will not block until the Webservice call to Datadog completes. The disadvantage is that if logging fails, you will not receive notification.
Note that the Datadog API returns Request accepted for processing (always 202 empty JSON) when it successfully ingests a log entry.
To configure the Datadog Logger Orchestration Component, on the Manage Components page:
- Next to the Datadog Logger component, click the Edit button. The Edit Component wizard appears.
- For Connection, select the Datadog Connection Connection.
- For Webservice Path, select Literal, and leave the value blank.
- For Method, select POST.
- Under Body, for Get value from, select JS Expression, and then set the value to an expression such as the following:
[
{
"ddsource": "conscia",
"ddtags": "env:staging",
"hostname": "i-012345678",
"message": "${contextField('logStatus')} ${contextField('logMessage')}",
"service": "orchestration",
"status": "${contextField('logStatus')}"
}
]
Note that this body is an array; you could pass mulitple log entries in a single call.
You can pass context such as the following to the Datadog Logger Component:
{
logEntry : {
"logMessage": "This is the message to log.",
"logSession": "{YOUR_INITIALS}",
"logStatus": "DEBUG"
}
}
Using Datadog Logger as a Sub Component
To use the Datadog Logger Component as a Subcomponent, in DX Studio:
- In the top navigation, click Manage Experiences, and then click Components. The Manage Components page appears.
- Next to the component that will use the Datadog Logger Component as a Subcomponent, click the Edit button. The Edit Component wizard appears.
- From the drop-down at the top right, select Sub Components. Note: the drop-down may have a scrollbar.
- Under Sub Components, click Add another item.
- For Property Name, enter a key in which the response from the Sub Component will appear in the response from the invoking Component.
- Under Component Codes, add the Datadog Logger (
datadog-logger
) Component. - Under Context Field for Sub Component, click Add another item.
- For Context Field, enter logMessage.
- For Expression, enter a JavaScript expression that returns the data to log.
- Click Submit.
You can set Expression to a value such as response
or a key within that value. Note that DX Engine invokes Sub Commponents for a Component before invoking Response Transformation.