Get started with Extensions 2.0
Dynatrace version 1.213+
Extensions 2.0 is a brand-new Dynatrace extension framework.
Dynatrace version 1.213 introduces a minimal scope of the Extensions 2.0 framework. Currently, it's limited to the capability of distributing the JSON definitions of dashboards and custom events for alerting via extensions. For more information on what's coming for Extensions 2.0, see Extend Dynatrace automation and AI capabilities more easily than ever on Dynatrace Product News.
To create a basic extension
To add extension to your Dynatrace environment
After you add and enable your extension, manage its lifecycle
The Extensions 2.0 framework isn't compatible with classic extensions and isn't related to Dynatrace third-party integrations.
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
- API v2
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.
- Display the dashboard.
- Select Edit.
- Switch to the Settings tab.
- Select the Advanced settings link.
- Select Dashboard JSON.
- On the Dashboard JSON page, select Download.
A JSON file with the dashboard's name is downloaded to your local machine. For more information, see Edit dashboard JSON.
- From the navigation menu, select Dashboards and display the dashboard of your choice.
- In the dashboard URL, find the
id
parameter (for example,id=d996b25e-593c-4213-8ad3-c87319a8830a
) and save the parameter value. - Use the Get a dashboard API endpoint to get the dashboard JSON definition.
Run the following command to get the dashboard definition. For this example, we use the Dynatrace SaaS URL:
Replace:curl -X GET "https://{env-id}.live.dynatrace.com/api/config/v1/dashboards/{dashboard-id}" \ -H "accept: application/json; charset=utf-8" \ -H "Authorization: Api-Token `{api-token}"
{env-id}
with your Environment ID{api-token}
with the API token with the required permissions.{dashboard-id}
with the dashboard identifier you determined in the previous step.
- The call returns the JSON payload containing the dashboard definition. Save it as a JSON file.
Export custom event for alerting definition
- From the navigation menu, select Settings > Anomaly detection > Custom events for alerting.
- Select the pencil button next to the alert of your choice.
- In the URL, find the
id
parameter (for example,id=1be8d58d-71a7-4566-9058-754d635363ab
) and save the parameter value. - Run the following command to get the definition of the custom event for alerting. For this example, we use the Dynatrace SaaS URL:
Replace: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}"
{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
- 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.
extensions.yaml
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 withcustom:
. The string must comply with the metric ingestion protocol requirements for dimensions.version
—the version of your extension inmajor
.minor
.build
format, such as1.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 theextension.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 theextension.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
- From the navigation menu, select Settings > Web and mobile monitoring > Credential vault.
- Select Add new credential.
- For Credential type, select Public Certificate.
- Add a meaningful Credential name.
- Upload the Certificate file.
- 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 permissionsMyCustomExtension.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"
}