> For the complete documentation index, see [llms.txt](https://docs.deltastream.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.deltastream.io/reference/sql-syntax/ddl/create-metrics-integration.md).

# CREATE METRICS INTEGRATION

## Syntax <a href="#synopsis" id="synopsis"></a>

```sql
CREATE METRICS INTEGRATION 
    metrics_integration_name 
WITH (metrics_integration_parameter = value [, ... ]);
```

### Description

Metrics integrations make it possible for organizations to configure an integration that enables scraping of query metrics.

### Arguments

#### **metrics\_integration\_name**

Specifies the name of the new metrics integration. If the name is case-sensitive, you must wrap it in double quotes; otherwise, the system uses the lower case name.

#### **token.expires\_in\_days**

Number of days that this token is valid for. Default: 90 days.

#### **metrics**

Optionally selects standard metrics to export. Provide a comma-separated list of metric names. Names are case-insensitive.

Supported values are `numRecordsInPerSecond`, `numRecordsOutPerSecond`, `numBytesInPerSecond`, `numBytesOutPerSecond`, and `consumerRecordsLagMax`.

Omit this property to export all standard metrics.

#### **aggregation\_levels**

Controls the metric output levels. Provide a comma-separated list of lowercase values: `raw`, `query`, or `task`.

The default is `raw`. Select any combination of `raw`, `query`, and `task`, including all three.

The `query` and `task` levels return recorded aggregate metrics instead of raw operator samples. This can reduce samples returned by the `/metrics` endpoint. Use `aggregation_types` to select the aggregate values to export.

#### **aggregation\_types**

Controls aggregate values for `query` and `task` levels. Provide a comma-separated list of lowercase values: `avg`, `min`, `max`, `sum`, or `count`.

This property is required when selecting `query` or `task`. It does not apply to `raw` metrics.

## Examples

#### Create a metrics integration

The following creates a new metrics integration named `my-integration`. It exports raw metrics and is valid for `AWS us-east-1`:

```sh
demodb.public/demostore# CREATE METRICS INTEGRATION "my-integration";
+---------------------+----------------+----------+------------------------------------------+-------------------+------------------------+
|  Type               |  Name          |  Command |  Summary                                 |  Token            |  Uri                   |
+=====================+================+==========+==========================================+===================+========================+
| metrics integration | my-integration | CREATE   | metrics integration my-integration was   | <my access token> | https://uri/to/metrics |
|                     |                |          | successfully created                     |                   |                        |
+---------------------+----------------+----------+------------------------------------------+-------------------+------------------------+
```

#### Export query and task aggregates

The following exports average and maximum lag metrics at query and task levels:

```sql
CREATE METRICS INTEGRATION lag_alert
WITH (
  'metrics' = 'consumerRecordsLagMax',
  'aggregation_levels' = 'query,task',
  'aggregation_types' = 'avg,max'
);
```

This integration exports these recorded metric families:

* `consumerRecordsLagMax:query:avg`
* `consumerRecordsLagMax:query:max`
* `consumerRecordsLagMax:task:avg`
* `consumerRecordsLagMax:task:max`

The command will output a URI and token you can add as a metric endpoint in Prometheus in Grafana. See [#guide-to-add-metrics-integration-to-prometheus](#guide-to-add-metrics-integration-to-prometheus "mention") for more information.\
\
If you have an active query you can test the URI and token with the following curl command. Use the URI from CREATE METRICS INTEGRATION output:

```
curl https://api-atyo2.deltastream.io/metrics -H "Accept: text/plain" -H "Authorization: Bearer [my access token]"
```

#### Example aggregate output

For the `lag_alert` integration, the endpoint returns recorded query and task aggregates like these:

```
# TYPE consumerRecordsLagMax:query:avg untyped
consumerRecordsLagMax:query:avg{organization_id="<org-UUID>",query_id="<query-UUID>",query_name="pageviews_metrics",query_version="1"} 12.5 1715802519327
# TYPE consumerRecordsLagMax:query:max untyped
consumerRecordsLagMax:query:max{organization_id="<org-UUID>",query_id="<query-UUID>",query_name="pageviews_metrics",query_version="1"} 42 1715802519327
# TYPE consumerRecordsLagMax:task:avg untyped
consumerRecordsLagMax:task:avg{organization_id="<org-UUID>",query_id="<query-UUID>",query_name="pageviews_metrics",query_version="1",task_name="source-pageviews"} 10 1715802519327
# TYPE consumerRecordsLagMax:task:max untyped
consumerRecordsLagMax:task:max{organization_id="<org-UUID>",query_id="<query-UUID>",query_name="pageviews_metrics",query_version="1",task_name="source-pageviews"} 42 1715802519327
```

Query aggregates retain `organization_id` and `query_id`. Task aggregates also retain `task_name`. `query_name` and `query_version` appear when available. Values and timestamps depend on the recorded series. Missing recorded series produce no samples.

#### Example raw output

If there's a query running the output of the above curl should look like:

{% code title="Prometheus raw output" %}

```
```

{% endcode %}

```
# TYPE deltastream_query_consumerRecordsLagMax untyped
deltastream_query_consumerRecordsLagMax{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSource:pageviews_all"} 0 1715802519327
# TYPE deltastream_query_numBytesInPerSecond untyped
deltastream_query_numBytesInPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSource:pageviews_all"} 90 1715802519327
deltastream_query_numBytesInPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSink:pageviews_all_metrics"} 0 1715802519327
# TYPE deltastream_query_numBytesOutPerSecond untyped
deltastream_query_numBytesOutPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSource:pageviews_all"} 0 1715802519327
deltastream_query_numBytesOutPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSink:pageviews_all_metrics"} 202 1715802519327
# TYPE deltastream_query_numRecordsInPerSecond untyped
deltastream_query_numRecordsInPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSource:pageviews_all"} 1 1715802519327
deltastream_query_numRecordsInPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSink:pageviews_all_metrics"} 1 1715802519327
# TYPE deltastream_query_numRecordsOutPerSecond untyped
deltastream_query_numRecordsOutPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSource:pageviews_all"} 1 1715802519327
deltastream_query_numRecordsOutPerSecond{organization_id="<org-UUID>",query_id="<query-UUID>",relation="KafkaSink:pageviews_all_metrics"} 1 1715802519327
```

## Guide to Add Metrics Integration to Prometheus

{% content-ref url="/pages/xxnZJdIKGhADraEu7r6g" %}
[Prometheus Integration](/reference/metrics/prometheus-integration.md)
{% endcontent-ref %}