Get started with Extensions 2.0

Dynatrace version 1.213+

Extensions 2.0 is a brand-new Dynatrace extension framework.

To create a basic extension

1. Export extension assets
2. Create extension YAML file
3. Create extension ZIP archive
4. Sign extension

To add extension to your Dynatrace environment

1. Upload extension
2. Enable extension

After you add and enable your extension, manage its lifecycle

• Update extension
• Delete extension

Prerequisites

• Dynatrace version 1.213+
• API token with the following permissions:
  • API v2
    • Read extensions
    • Write extensions
    • Read extension environment configurations
    • Write extension environment configurations
  • API v1
    • Read configuration
    • Write configuration

Basic concepts

To understand how to manage the extension lifecycle using Extensions 2.0 API, familiarize yourself with the following Extensions 2.0 concepts.

Extension package

Extensions are provided as a ZIP package containing only the extension.zip archive and the extension.zip.sig signature file. Extension packages with different contents are not accepted for upload. The maximum size of the extension package is 1 MB.

Extension ZIP archive

The archive contains

• Extension YAML file
• Assets (the JSON definitions of dashboards and custom events for alerting)

Digital signature

Dynatrace verifies the authenticity of an extension using a digital signature file generated against the root certificate. Using the signature file, Dynatrace checks whether the extension is provided by a trusted source, whether Dynatrace or a Dynatrace customer.

When you receive an extension from Dynatrace, it's already signed.

Configurations

An environment configuration defines your custom dashboards and custom events for alerting. Together, these comprise the extension assets. You activate an extension by enabling a version of the environment configuration. Your environment can store up to 10 extension versions, but only one version can be active at a time.

Export assets

You can add a maximum of 10 dashboards and 10 custom events for alerting definitions to the extension environment configuration.

Export dashboard definition

Export a dashboard definition through the Dynatrace web UI or Dynatrace API.

Export custom event for alerting definition

1. From the navigation menu, select Settings > Anomaly detection > Custom events for alerting.
2. Select the pencil button next to the alert of your choice.
3. In the URL, find the id parameter (for example, id=1be8d58d-71a7-4566-9058-754d635363ab) and save the parameter value.
4. Run the following command to get the definition of the custom event for alerting. For this example, we use the Dynatrace SaaS URL:

   curl -X GET "https://{env-id}.live.dynatrace.com/api/config/v1/anomalyDetection/metricEvents/{custom-event-id}" \
   -H "accept: application/json; charset=utf-8" \
   -H "Authorization: Api-Token `{api-token}"
   

   Replace:
   • {env-id} with your Environment ID
   • {api-token} with the API token with the required permissions.
   • {custom-event-id} with the custom event for alerting identifier you determined in the previous step
5. The call returns the JSON payload containing the custom event for alerting definition. Save it as a JSON file.

Create extension YAML file

The extension must contain the YAML file providing basic information about the extension and references to assets.

name: custom:my.company.extension
version: 1.0.0
minDynatraceVersion: "1.213"
author:
  name: "My Company"
dashboards:
    - path: "dashboards/dashboard.json"
  
alerts:
    - path: "alerts/alert.json"

• name—the name of your extension. A custom extension names (an extension not developed by Dynatrace) must start with custom:. The string must comply with the metric ingestion protocol requirements for dimensions.
• version—the version of your extension in major.minor.build format, such as 1.0.0. Your Dynatrace environment can store 10 extension versions, but only one can be active at the time.
• minDynatraceVersion—the earliest Dynatrace version supported by the extension enclosed in quotes ("), such as "1.213".
• author—the extension developer or company.
• dashboards—the path to the dashboard definitions in the extension.zip archive relative to the extension YAML file. You can add up to 10 definitions.
• alerts—the path to the custom events for alerting definitions in the extension.zip archive relative to the extension YAML file. You can add up to 10 definitions.

Create extension ZIP archive

Using the YAML from the example above, the files in the extension.zip archive should be organized as follows:

extension.zip
│   extension.yaml
│
└───alerts
│   |   alert.json
│   
└───dashboards
    │   dashboard.json

Sign extension ZIP archive

Each extension uploaded to a Dynatrace environment must be signed so that Dynatrace can verify the authenticity of the extension. Use OpenSSL to sign your extension. For Windows, you need to download and install an OpenSSL binary of your choice.

Create the root key and certificate

Your company developers will issue their own certificates from your company root certificate. When developers sign their extensions with their own developer certificates, Dynatrace will be able the verify the extension authenticity against your root certificate stored in the Dynatrace credential vault.

Run the following commands to generate your organization's root certificate. Do not set the password. Password-protected certificates are not supported by Dynatrace.

openssl genrsa -out ca_one.key 2048

openssl req -days 10000 -new -x509 -key ca_one.key -out ca_one.crt

openssl rsa -in ca_one.key -pubout -out ca_one.pub.key

This generates your ca_one.crt root certificates. Dynatrace accepts only PFX, P12 and PEM formats, so you need to convert the CRT certificate to one of the allowed formats. For example:

openssl pkcs12 -export -in ca_one.crt -nokeys -out ca_one.p12

Add your root certificate to the Dynatrace credential vault

1. From the navigation menu, select Settings > Web and mobile monitoring > Credential vault.
2. Select Add new credential.
3. For Credential type, select Public Certificate.
4. Add a meaningful Credential name.
5. Upload the Certificate file.
6. Select Save.

Create a developer certificate signing request

Run the following commands to generate the certificate signing request to the root CA.

openssl genrsa -out developer.key 2048

openssl rsa -in developer.key -pubout -out developer.pub.key

openssl req -new -key developer.key -out developer.csr

The result is the developer.csr certificate signing request that you'll use to issue the developer certificate from the root certificate.

Create a developer certificate

Run the following command to generate the developer certificate

openssl x509 -req -days 10000 -in developer.csr -CA ca_one.crt -CAkey ca_one.key -CAcreateserial -out developer.crt

The result is the developer.crt you'll use for signing your extensions.

Sign the extension

Finally, use the following command to sign your extension. Make sure that your extension.zip file is in the directory from which you run the command.

openssl cms -sign -signer developer.crt -inkey developer.key -binary -in extension.zip -outform PEM -out extension.zip.sig

The result is an extension.zip.sig signature file. Compress it together with the extension ZIP archive and give it any name; it is referred to later in this topic as MyCustomExtension.zip.

Upload the extension

Run the following command to upload the extension package to your environment. For this example, we use the Dynatrace SaaS URL:

curl -X POST "https://{env-id}.live.dynatrace.com/api/v2/extensions" \
-H "accept: application/json; charset=utf-8" \
-H "Authorization: Api-Token `{api-token}" \
-H "Content-Type: multipart/form-data" \
-F "file=@MyCustomExtension.zip;type=application/zip"

Replace:

• {env-id} with your Environment ID
• {api-token} with the API token with the required permissions
• MyCustomExtension.zip with the actual name of your extension package

After a successful upload, the Dynatrace API returns basic extension details, including the extension name, version, and minimum Dynatrace version required to run the extension:

{
   "extensionName":"custom:my.company.extension",
   "version":"1.0.0",
   "author":{
      "name":"My Company"
   },
   "dataSources":[
      
   ],
   "variables":[
      
   ],
   "featureSets":[
      
   ],
   "minDynatraceVersion":"1.213.0"
}

Enable extension

After you upload the extension to your environment, you need to enable the environment configuration. This step is necessary because you can upload up to 10 extension versions but you can use only one extension version at the time. When you activate the extension, you specify which extension version to use.

Run the following command to activate the extension in your environment. For this example, we use the Dynatrace SaaS URL.

curl -X PUT "https://{env-id}.live.dynatrace.com/api/v2/extensions/{extensionName}/environmentConfiguration" \
-H "accept: application/json; charset=utf-8" \
-H "Authorization: Api-Token `{api-token}" \
-H "Content-Type: application/json; charset=utf-8" \
-d "{\"version\":\"{version}\"}"

Replace:

• {env-id} with your Environment ID
• {api-token} with the API token with required permissions
• {extensionName} with the actual extension name
• {version} with the extension version you want to activate

To determine the extension name, extract the extension package, extract the extensions.zip file from the package, and open the extensions.yaml file.

After a successful activation, the Dynatrace API returns the version of the activated extension. For example:

{"version":"1.0.0"}

Update extension

To update an extension, you need to upload the new extension package and enable the new environment configuration.

Upload updated extension package

To upload the package, use the same command you used to upload the initial version of the extension. You need to use the new extension package filename if it changed.

Enable new configuration version

To enable the environment configuration version, you need to add the version parameter to the API call. Use one of these methods to determine the version:

• After a successful upload, the Dynatrace API returns basic extension details, including the version.
• Find the version in the extensions.yaml file inside the extension package.
• Run the Get extension versions API call.

Run the following command to activate the new version. For this example, we use the Dynatrace SaaS URL.

curl -X PUT "https://{env-id}.live.dynatrace.com/api/v2/extensions/{extensionName}/environmentConfiguration" \
-H "accept: application/json; charset=utf-8" \
-H "Authorization: Api-Token  `{api-token}" \
-H "Content-Type: application/json; charset=utf-8" \
-d "{\"version\":\"{version}\"}"

Replace:

• {env-id} with your Environment ID
• {api-token} with the API token with required permissions
• {extensionName} with the actual extension name
• {version} with the extension version you want to activate

After a successful activation, the Dynatrace API returns the version of the activated extension. For example:

{"version":"1.1.0"}

If you need to revert activation to an earlier version, run the command above with a different version parameter.

Delete extension

If you uploaded a number of extension versions, you need to delete all the versions to remove the extension completely from your environment. You can use GET extension versions to list all the extension versions available in your environment.

Delete environment configuration

To delete currently active environment configuration, use DELETE environment configuration. For this example, we use the Dynatrace SaaS URL.

curl -X DELETE "{env-id}.live.dynatrace.com/api/v2/extensions/{extensionName}/environmentConfiguration" \
-H "accept: application/json; charset=utf-8" \
-H "Authorization: Api-Token `{api-token}"

Replace:

• {env-id} with your Environment ID
• {api-token} with the API token with required permissions
• {extensionName} with the actual extension name

After a successful deactivation, the Dynatrace API returns the version of the deactivated extension. For example:

{"version":"1.1.0"}

Delete extension version

To delete an extension version, use DELETE an extension version. In this example, we use the Dynatrace SaaS URL.

curl -X DELETE "{env-id}.live.dynatrace.com/api/v2/extensions/{extensionName}/{version}" \
-H "accept: application/json; charset=utf-8" \
-H "Authorization: Api-Token `{api-token}" 

Replace:

• {env-id} with your Environment ID
• {api-token} with the API token with required permissions
• {extensionName} with the actual extension name
  • {version} with the extension version you want to delete

After a successful version deletion, Dynatrace API returns the following response:

{
   "extensionName":"custom:my.company.extension",
   "version":"1.0.0",
   "author":{
      "name":"My Company"
   },
   "dataSources":[
      
   ],
   "variables":[
      
   ],
   "featureSets":[
      
   ],
   "minDynatraceVersion":"1.213.0"
}