---
layout: docs
page_title: APM Plugins
description: Learn how to author a Nomad Autoscaler APM plugin.
---

# APM Plugins

APM plugins are used by the autoscaler to interact with an external APM system,
returning metrics that are used by the autoscaler to inform scaling actions.

For a real-world example of a Nomad APM plugin implementation, see the
[`prometheus` plugin](https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/apm/prometheus).

## Authoring APM Plugins

Authoring an APM plugin in Go can be accomplished by implementing the
[`apm.APM`][apm_plugin] interface, alongside a `main` package to launch the plugin.

The [`no-op` APM plugin][noop_plugin] can be used as a starting point for new APM
plugins.

## APM Plugin API

The [base plugin][base_plugin] interface must be implemented in addition to the
following functions.

#### `Query(query string, timeRange sdk.TimeRange) (sdk.TimestampedMetrics, error)`

The `Query` function is called by the agent during policy
evaluation. The `query` argument is the opaque string from the scaling policy,
and the `timeRange` indicates the period of time over which the query should be
made. The response is a series of timestamped metrics; as such, the query semantics
should be such that the backing APM will return a time series. An example is the
CPU utilization of a task group, averaged over all current allocations.

#### `QueryMultiple(query string, timeRange sdk.TimeRange) ([]sdk.TimestampedMetrics, error)`

The `QueryMultiple` method is similar to `Query`, except that the interface allows
multiple time series to be returned. This endpoint is currently only used for
[Dynamic Application Sizing][das].
An example would be to return the CPU utilization for all allocations during
the time range.

[apm_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/apm/apm.go#L11
[base_plugin]: /tools/autoscaling/internals/plugins/base
[noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-apm
[das]: /tools/autoscaling#dynamic-application-sizing
