OneAgent and ActiveGate version 1.299 are the last versions supporting OneAgent and ActiveGate Extensions 1.0 framework. You can continue using Extensions 1.0 if you stay at OneAgent or ActiveGate version 1.299. Note that this means you'll be using an unsupported Python version 3.8. We strongly recommend migrating your extensions to the latest Extensions 2.0 framework.
For more information, see General guidance and how to migrate.
The plugin.json
is your extension definition. Starting with the metrics used by the extension to the favicon and extension configuration fields.
Logically, it can be divided into four parts:
Example:
{"name": "custom.remote.python.example","version": "1.17","productiveMinVersion": "1.000","requiredAgentVersion": "1.000","type": "python","entity": "CUSTOM_DEVICE","metricGroup": "tech.Example_Service","technologies": ["EXAMPLE_SERVICE"],"source": {"package": "demo_activegate_plugin_multi","className": "RemoteExamplePlugin","install_requires": ["requests>=2.6.0"],"activation": "Remote"},"ui": {"keymetrics": [{"key": "databases.table_size","aggregation": "max","mergeaggregation": "sum","displayname": "Total table size"}],"keycharts": [{"group": "Service state","title": "State","series": [{"key": "service.state_5","displayname": "Status","seriestype": "bar","statecolors": ["#ff3333", "#ffd633", "#00b33c"],"statechart": true}]},{"group": "Disk usage","title": "Total disk usage","series": [{"key": "databases.table_size","displayname": "Sum of databases size","seriestype": "area","color": "#74cff7"}]}],"charts": [{"group": "Memory","title": "Per table usage","series": [{"key": "databases.table_size","displayname": "Per table size","seriestype": "area","color": "#74cff7","metricexplanation": "How big is each table"}]},{"group": "Entries","title": "Total num entries","series": [{"key": "databases.total_num_entities","displayname": "Total number of entries","seriestype": "line","color": "#74cff7","metricexplanation": "How big is each table"}]},{"group": "Entries","title": "Archives","series": [{"key": "databases.replicated_entries","displayname": "Number of entries archived","seriestype": "bar","color": "#74cff7","metricexplanation": "Number of metrics moved to archive"}]},{"group": "Connections","title": "Archives","series": [{"key": "service.querries_per_second","displayname": "Connections per second","seriestype": "bar","color": "#74cff7","metricexplanation": "Connections per second"}]}]},"metrics": [{"statetimeseries": {"key": "service.state_5","states": ["DOWNTIME", "MAINTENANCE", "WORKING"],"displayname": "Service State","source": { "state_entrypoint": "/api/state" }},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "service.querries_per_second","unit": "PerSecond","displayname": "Querries per second","aggregation": "AVG"},"entity": "CUSTOM_DEVICE_GROUP","alert_settings": [{"alert_id": "custom_connections_alert","event_type": "AVAILABILITY_EVENT","event_name": "No connections!","description": "The {metricname} of {severity} is {alert_condition} the threshold of {threshold}","threshold": 0.01,"alert_condition": "ABOVE","samples": 5,"violating_samples": 1,"dealerting_samples": 5}]},{"timeseries": {"key": "databases.table_size","unit": "MegaByte","displayname": "Table size","aggregation": "MAX","dimensions": ["table_name"]},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "databases.total_num_entities","unit": "Count","displayname": "Total num ","aggregation": "MAX"},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "databases.replicated_entries","unit": "Count","displayname": "Archived Entries","aggregation": "SUM"},"entity": "CUSTOM_DEVICE"}],"properties": [{"key": "url","type": "String"},{"key": "auth_user","type": "String"},{"key": "auth_password","type": "Password"},{"key": "state_interval","type": "Integer","defaultValue": 60},{"key": "alert_interval","type": "Integer","defaultValue": 360},{"key": "event_interval","type": "Integer","defaultValue": 240},{"key": "relative_interval","type": "Integer","defaultValue": 60}],"configUI": {"displayName": "CustomCloudTechnology","properties": [{"key": "url","displayName": "URL","displayOrder": 3,"displayHint": "http://localhost:9200/"},{"key": "auth_user","displayName": "User","displayOrder": 1,"displayHint": "Leave empty if no authentication is set up"},{"key": "auth_password","displayName": "Password","displayOrder": 2,"displayHint": "Leave empty if no authentication is set up","defaultValue": "somepassword"},{"key": "state_interval","displayName": "State change interval","displayOrder": 3,"displayHint": "How often state metrics changes","defaultValue": 60},{"key": "alert_interval","displayName": "Alert interval","displayOrder": 4,"displayHint": "How often an alert is raised","defaultValue": 360},{"key": "event_interval","displayName": "Event interval","displayOrder": 5,"displayHint": "How often an event is raised","defaultValue": 240},{"key": "relative_interval","displayName": "Relative interval","displayOrder": 6,"displayHint": "How often relative metric is submitted","defaultValue": 60}]}}
The top-level metadata section contains a list of properties used to identify your extension.
The source
section lists the package name and class that is to be imported and executed by ActiveGate. This corresponds to the name of the Python file that contains the code and the name of the class that’s defined in it. This information is required by the ActiveGate Plugin Module Python engine.
{"package": "remote_example","className": "RemoteExamplePlugin","install_requires": ["requests>=2.6.0"]}
The technologies
and favicon
properties determine how your technology is presented on the Technology overview page.
To have the data from your extension displayed on an existing technology tile, set a corresponding technology name. You can look up the configured technology names in the ActiveGate extensions JSON reference
or you can get them from the UI as the Main technology
process property.
If a value of the technologies
property doesn't map to an existing one, the extension will create a new tile on the Technology overview page. The Favicon property determines the technology tile displayed on the page:
You can't deploy the same extension version twice. To upload a modified extension, make sure you increment the extension version with every build or upload.
ActiveGate extension name should follow ^ custom.remote.python (\.[a-zA-Z0-9_]+)+$
regex. For example, custom.remote.python.demo
. The name of each extension must be unique.
The preferred way of using Metric Group is adding prefix "tech" before your metric group definition. For example "tech.elasticsearch". Thanks to this, other users will be able to find additional metrics alongside with others in the context of technology like in this example on Custom Charts page:
MetricGroup
field can be also used to create a completely new entry. Note that you can use dots to create subgroups, like in this example "My_Metrics.plugins":
However, setting metricGroup
field is not necessary for already running extensions that originally didn't have is set. In such a case, metricGroup
will be automatically set the extension name not to break the continuity of your data.
This part of the JSON defines how metrics are charted on the Dynatrace page. It contains an optional charts section and an optional keycharts section.
Example UI section:
{"ui": {"keymetrics": [{"key": "databases.table_size","aggregation": "max","mergeaggregation": "sum","displayname": "Total table size"}],"keycharts": [{"group": "Service state","title": "State","series": [{"key": "service.state_5","displayname": "Status","seriestype": "bar","statecolors": ["#ff3333", "#ffd633", "#00b33c"],"statechart": true}]},{"group": "Disk usage","title": "Total disk usage","series": [{"key": "databases.table_size","displayname": "Sum of databases size","seriestype": "area","color": "#74cff7"}]}],"charts": [{"group": "Memory","title": "Per table usage","series": [{"key": "databases.table_size","displayname": "Per table size","seriestype": "area","color": "#74cff7","metricexplanation": "How big is each table"}]},{"group": "Entries","title": "Total num entries","series": [{"key": "databases.total_num_entities","displayname": "Total number of entries","seriestype": "line","color": "#74cff7","metricexplanation": "How big is each table"}]},{"group": "Entries","title": "Archives","series": [{"key": "databases.replicated_entries","displayname": "Number of entries archived","seriestype": "bar","color": "#74cff7","metricexplanation": "Number of metrics moved to archive"}]},{"group": "Connections","title": "Archives","series": [{"key": "service.querries_per_second","displayname": "Connections per second","seriestype": "bar","color": "#74cff7","metricexplanation": "Connections per second"}]}]}}
The KeyMetrics
section is optional and allows you to define up to two metrics that should be part of the Custom Device infographic.
{"keymetrics": [{"key": "databases.table_size","aggregation": "max","mergeaggregation": "sum","displayname": "Total table size"}]}
Here is an example of a keymetric in web UI:
A keymetric has the following attributes:
Array item definition:
Both KeyCharts and Charts have the same object structure, for example:
{"keycharts": [{"group": "Service state","title": "State","series": [{"key": "service.state_5","displayname": "Status","seriestype": "bar","statecolors": ["#ff3333", "#ffd633", "#00b33c"],"statechart": true}]},{"group": "Disk usage","title": "Total disk usage","series": [{"key": "databases.table_size","displayname": "Sum of databases size","seriestype": "area","color": "#74cff7"}]}]}
Keycharts are visible on each Process page:
Other charts are available after drilling down to the Further details section of each Process page.
Both chart and keychart sections are an array of objects:
Array item definition:
Where series is an array of objects:
Array item definition:
This part of the JSON is an array and defines which metrics are fetched by the extension. Each metric is defined by independently by JSON. There are two types of metrics available: timeseries and statetimeseries
[{"statetimeseries": {"key": "service.state_5","states": ["DOWNTIME", "MAINTENANCE", "WORKING"],"displayname": "Service State","source": { "state_entrypoint": "/api/state" }},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "service.querries_per_second","unit": "PerSecond","displayname": "Querries per second","aggregation": "AVG"},"entity": "CUSTOM_DEVICE_GROUP","alert_settings": [{"alert_id": "custom_connections_alert","event_type": "AVAILABILITY_EVENT","event_name": "No connections!","description": "The {metricname} of {severity} is {alert_condition} the threshold of {threshold}","threshold": 0.01,"alert_condition": "ABOVE","samples": 5,"violating_samples": 1,"dealerting_samples": 5}]},{"timeseries": {"key": "databases.table_size","unit": "MegaByte","displayname": "Table size","aggregation": "MAX","dimensions": ["table_name"]},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "databases.total_num_entities","unit": "Count","displayname": "Total num ","aggregation": "MAX"},"entity": "CUSTOM_DEVICE"},{"timeseries": {"key": "databases.replicated_entries","unit": "Count","displayname": "Archived Entries","aggregation": "SUM"},"entity": "CUSTOM_DEVICE"}]
Array item have to match one of:
Where timeseries and statetimeseries are defined as:
Both timeseries and statetimeseries can define alerts. To do it, use the alert_settings
which is an array of objects, where each object looks like:
{"alert_id": "custom_connections_alert","event_type": "AVAILABILITY_EVENT","event_name": "No connections!","description": "The {metricname} of {severity} is {alert_condition} the threshold of {threshold}","threshold": 0.01,"alert_condition": "ABOVE","samples": 5,"violating_samples": 1,"dealerting_samples": 5}
Array item definition:
The extension configuration section controls the extension data appearance in the web UI at Settings > Monitoring > Monitored technologies and its configuration, for example: user name, password, connection string, etc. The configUI
section defines the configuration fields that are displayed in the UI. The properties
section defines the configuration properties that are sent to the extension.
Example ConfigUI section:
{"configUI": {"displayName": "CustomCloudTechnology","properties": [{"key": "url","displayName": "URL","displayOrder": 3,"displayHint": "http://localhost:9200/"},{"key": "auth_user","displayName": "User","displayOrder": 1,"displayHint": "Leave empty if no authentication is set up"},{"key": "auth_password","displayName": "Password","displayOrder": 2,"displayHint": "Leave empty if no authentication is set up","defaultValue": "somepassword"},{"key": "state_interval","displayName": "State change interval","displayOrder": 3,"displayHint": "How often state metrics changes","defaultValue": 60},{"key": "alert_interval","displayName": "Alert interval","displayOrder": 4,"displayHint": "How often an alert is raised","defaultValue": 360},{"key": "event_interval","displayName": "Event interval","displayOrder": 5,"displayHint": "How often an event is raised","defaultValue": 240},{"key": "relative_interval","displayName": "Relative interval","displayOrder": 6,"displayHint": "How often relative metric is submitted","defaultValue": 60}]}}
This is how it looks in Monitored Technologies:
Note the two additional fields:
ConfigUI is an array of objects:
Properties is an array of objects that are used to define fields for extension configuration page:
Array item definition:
Example Properties section:
{"properties": [{"key": "url","type": "String"},{"key": "auth_user","type": "String"},{"key": "auth_password","type": "Password"},{"key": "state_interval","type": "Integer","defaultValue": 60},{"key": "alert_interval","type": "Integer","defaultValue": 360},{"key": "event_interval","type": "Integer","defaultValue": 240},{"key": "relative_interval","type": "Integer","defaultValue": 60}]}
Properties is an array of objects:
Array item definition: