Version detection strategies for deep-monitored processes

Dynatrace uses built-in version detection strategies to support different technology standards for versioning. The latest version detected can be influenced by environment variables, Kubernetes labels, and events ingestion.

Environment variables

The best and easiest way to get version information also available on every distributed trace is to provide metadata via environment variables.

DT_RELEASE_VERSION for Version
DT_RELEASE_STAGE for Stage
DT_RELEASE_PRODUCT for Product
DT_RELEASE_BUILD_VERSION for Build version

Examples

In Linux,
1. Run the following command, making sure to replace <version> with your actual release value.
```
export DT_RELEASE_VERSION=<version>
```
Example command:
```
export DT_RELEASE_VERSION=0.4.1
```
1. Start the process.
After a few seconds, the version of this process will appear in Dynatrace.

In Windows,

Run the following commands, making sure to replace <version>, <build-version>, <release-product-name>, and <release-stage> with your actual values.

set DT_RELEASE_VERSION=<version>
set DT_RELEASE_BUILD_VERSION=<build-version>
set DT_RELEASE_PRODUCT=<release-product-name>
set DT_RELEASE_STAGE=<release-stage>

Example command:

set DT_RELEASE_VERSION=0.4.1
set DT_RELEASE_BUILD_VERSION=2021-03-24
set DT_RELEASE_PRODUCT=WoGo Main
set DT_RELEASE_STAGE=production

Start the process.

After a few seconds, the version of this process will appear in Dynatrace.

Kubernetes labels

Best practice

We recommend that you propagate Kubernetes labels to environment variables in the deployment configuration.

Example:

K8s best practice

Starting with Dynatrace Operator version 0.10.0+, you can configure release label propagation by setting the feature.dynatrace.com/label-version-detection=true feature flag in the DynaKube custom resource. For details, see Configure build label propagation.

You can use

Kubernetes pod labels to provide metadata for:
- The stage of a release (label: dynatrace-release-stage)
Kubernetes recommended labels for deployed pods to provide metadata for:
- Related versions (label: app.kubernetes.io/version)
- A related product (label: app.kubernetes.io/part-of) optional

Be sure to use only pod labels, not the Kubernetes workload labels.

Kubernetes recommended labels mapped to release metadata:

Recommended labels

Dynatrace OneAgent with viewer permissions on the namespace can automatically detect labels attached to the Kubernetes pods.

Version and Product show up in the release inventory.
Kubernetes namespaces or configured Dynatrace host-group names show up as Stages in the release inventory.

If you need to update version information, update the deployment configuration to include the updated label and redeploy the pods. This ensures that DT_RELEASE_VERSION environment variable is correctly set when the pod starts. For more information, see Configure build label propagation.

The command below will not propagate the updated label to the DT_RELEASE_VERSION environment variable used by OneAgent.

kubectl label --overwrite pod yourPodId -n yourNamespace app.kubernetes.io/version=42

Events ingestion

If it's inconvenient to add environment variables for processes in your environments, or if you want to update version information without environment variable changes for your deployed software, you can send custom deployment events to Dynatrace APIs that explicitly provide version information.

Version information sent via events can't be used to filter traces or metrics. Ensure that environment variables always indicate the currently deployed version.

The example JSON below shows how to send custom deployment events to the event ingestion API. Note that processes are matched via tags, resulting in an event for each process. The workflow, which subscribes to these events, gets triggered multiple times. We recommend sending a separate event to the workflow to avoid multiple executions.

For a release to be discovered, the following requirements must be fulfilled:

eventType is set to CUSTOM_DEPLOYMENT
entitySelector is mandatory and should point to a process group instance or a list of process group instances
dt.event.deployment.version is mandatory

Example:

{
  "eventType": "CUSTOM_DEPLOYMENT",
  "title": "Easytravel 1.1",
  "entitySelector": "type(PROCESS_GROUP_INSTANCE),tag(easytravel)",
  "properties": {
    "dt.event.deployment.name":"Easytravel 1.1",
    "dt.event.deployment.version": "1.1",
    "dt.event.deployment.release_stage": "production" ,
    "dt.event.deployment.release_product": "frontend",
    "dt.event.deployment.release_build_version": "123",
    "approver": "Jason Miller",
    "dt.event.deployment.ci_back_link": "https://pipelines/easytravel/123",
    "gitcommit": "e5a6baac7eb",
    "change-request": "CR-42",
    "dt.event.deployment.remediation_action_link": "https://url.com",
    "dt.event.is_rootcause_relevant": true
  }
}