mirror of https://github.com/istio/istio.io.git
471 lines
12 KiB
HTML
471 lines
12 KiB
HTML
---
|
|
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/istio' REPO
|
|
source_repo: https://github.com/istio/istio
|
|
title: Prometheus
|
|
description: Adapter that exposes Istio metrics for ingestion by a Prometheus harvester.
|
|
location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/prometheus.html
|
|
layout: protoc-gen-docs
|
|
generator: protoc-gen-docs
|
|
supported_templates: metric
|
|
aliases:
|
|
- /docs/reference/config/adapters/prometheus.html
|
|
number_of_entries: 8
|
|
---
|
|
<p>The <code>prometheus</code> adapter collects Istio metrics and makes them available to
|
|
<a href="https://prometheus.io">Prometheus</a>.</p>
|
|
|
|
<p>This adapter supports the <a href="/docs/reference/config/policy-and-telemetry/templates/metric/">metric template</a>.</p>
|
|
|
|
<h2 id="Params">Params</h2>
|
|
<section>
|
|
<p>Configuration format for the <code>prometheus</code> adapter.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-metrics">
|
|
<td><code>metrics</code></td>
|
|
<td><code><a href="#Params-MetricInfo">Params.MetricInfo[]</a></code></td>
|
|
<td>
|
|
<p>The set of metrics to represent in Prometheus. If a metric is defined in Istio but doesn’t have a corresponding
|
|
shape here, it will not be populated at runtime.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-metrics_expiration_policy">
|
|
<td><code>metricsExpirationPolicy</code></td>
|
|
<td><code><a href="#Params-MetricsExpirationPolicy">Params.MetricsExpirationPolicy</a></code></td>
|
|
<td>
|
|
<p>Optional. The rate at which to expire metrics from the adapter. This option controls the amount of metric data
|
|
that the adapter will maintain over its lifetime.</p>
|
|
|
|
<p>EXPERIMENTAL: This feature should only be used in advanced cases.</p>
|
|
|
|
<p>Example config stanza:</p>
|
|
|
|
<pre><code class="language-yaml">metricsExpirationPolicy:
|
|
metricsExpiryDuration: "5s"
|
|
expiryCheckIntervalDuration: "1s"
|
|
</code></pre>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo">Params.MetricInfo</h2>
|
|
<section>
|
|
<p>Describes how a metric should be represented in Prometheus.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-namespace">
|
|
<td><code>namespace</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Optional. The namespace is used as a prefix on the metric names.
|
|
An example: for a metric named <code>requests_total</code> with a namespace of <code>istio</code>,
|
|
the full metric name becomes <code>istio_requests_total</code>.
|
|
NOTE: The specified namespace should be a prometheus-safe name. If not, the adapter
|
|
will attempt to convert the namespace to a prometheus-safe name.
|
|
NOTE: Changing the value for this will potentially impact downstream integrations
|
|
and should be used with caution.
|
|
Default value: <code>istio</code>.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-name">
|
|
<td><code>name</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Recommended. The name is used to register the prometheus metric.
|
|
It must be unique across all prometheus metrics as prometheus does not allow duplicate names.
|
|
If name is not specified a sanitized version of instance_name is used.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-instance_name">
|
|
<td><code>instanceName</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Required. The name is the fully qualified name of the Istio metric instance
|
|
that this MetricInfo processes.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-description">
|
|
<td><code>description</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Optional. A human readable description of this metric.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-kind">
|
|
<td><code>kind</code></td>
|
|
<td><code><a href="#Params-MetricInfo-Kind">Params.MetricInfo.Kind</a></code></td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-buckets">
|
|
<td><code>buckets</code></td>
|
|
<td><code><a href="#Params-MetricInfo-BucketsDefinition">Params.MetricInfo.BucketsDefinition</a></code></td>
|
|
<td>
|
|
<p>For metrics with a metric kind of DISTRIBUTION, this provides a mechanism
|
|
for configuring the buckets that will be used to store the aggregated values.
|
|
This field must be provided for metrics declared to be of type DISTRIBUTION.
|
|
This field will be ignored for non-distribution metric kinds.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-label_names">
|
|
<td><code>labelNames</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>The names of labels to use: these need to match the dimensions of the Istio metric.
|
|
TODO: see if we can remove this and rely on only the dimensions in the future.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo-BucketsDefinition">Params.MetricInfo.BucketsDefinition</h2>
|
|
<section>
|
|
<p>Describes buckets for DISTRIBUTION kind metrics.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-linear_buckets" class="oneof oneof-start">
|
|
<td><code>linearBuckets</code></td>
|
|
<td><code><a href="#Params-MetricInfo-BucketsDefinition-Linear">Params.MetricInfo.BucketsDefinition.Linear (oneof)</a></code></td>
|
|
<td>
|
|
<p>The linear buckets.</p>
|
|
|
|
</td>
|
|
<td>
|
|
Yes
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-exponential_buckets" class="oneof">
|
|
<td><code>exponentialBuckets</code></td>
|
|
<td><code><a href="#Params-MetricInfo-BucketsDefinition-Exponential">Params.MetricInfo.BucketsDefinition.Exponential (oneof)</a></code></td>
|
|
<td>
|
|
<p>The exponential buckets.</p>
|
|
|
|
</td>
|
|
<td>
|
|
Yes
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-explicit_buckets" class="oneof">
|
|
<td><code>explicitBuckets</code></td>
|
|
<td><code><a href="#Params-MetricInfo-BucketsDefinition-Explicit">Params.MetricInfo.BucketsDefinition.Explicit (oneof)</a></code></td>
|
|
<td>
|
|
<p>The explicit buckets.</p>
|
|
|
|
</td>
|
|
<td>
|
|
Yes
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo-BucketsDefinition-Explicit">Params.MetricInfo.BucketsDefinition.Explicit</h2>
|
|
<section>
|
|
<p>Specifies a set of buckets with arbitrary widths.</p>
|
|
|
|
<p>There are <code>size(bounds) + 1</code> (= <code>N</code>) buckets. Bucket <code>i</code> has the following
|
|
boundaries:</p>
|
|
|
|
<ul>
|
|
<li>Upper bound (<code>0 <= i < N-1</code>): <code>bounds[i]</code></li>
|
|
<li>Lower bound (<code>1 <= i < N</code>): <code>bounds[i - 1]</code></li>
|
|
</ul>
|
|
|
|
<p>The <code>bounds</code> field must contain at least one element. If <code>bounds</code> has
|
|
only one element, then there are no finite buckets, and that single
|
|
element is the common boundary of the overflow and underflow buckets.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Explicit-bounds">
|
|
<td><code>bounds</code></td>
|
|
<td><code>double[]</code></td>
|
|
<td>
|
|
<p>The values must be monotonically increasing.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo-BucketsDefinition-Exponential">Params.MetricInfo.BucketsDefinition.Exponential</h2>
|
|
<section>
|
|
<p>Specifies an exponential sequence of buckets that have a width that is
|
|
proportional to the value of the lower bound. Each bucket represents a
|
|
constant relative uncertainty on a specific value in the bucket.</p>
|
|
|
|
<p>There are <code>num_finite_buckets + 2</code> (= <code>N</code>) buckets. The two additional
|
|
buckets are the underflow and overflow buckets.</p>
|
|
|
|
<p>Bucket <code>i</code> has the following boundaries:</p>
|
|
|
|
<ul>
|
|
<li>Upper bound (0 <= i < N-1): <code>scale * (growth_factor ^ i)</code></li>
|
|
<li>Lower bound (1 <= i < N): <code>scale * (growth_factor ^ (i - 1))</code></li>
|
|
</ul>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Exponential-num_finite_buckets">
|
|
<td><code>numFiniteBuckets</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Must be greater than 0.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Exponential-growth_factor">
|
|
<td><code>growthFactor</code></td>
|
|
<td><code>double</code></td>
|
|
<td>
|
|
<p>Must be greater than 1.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Exponential-scale">
|
|
<td><code>scale</code></td>
|
|
<td><code>double</code></td>
|
|
<td>
|
|
<p>Must be greater than 0.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo-BucketsDefinition-Linear">Params.MetricInfo.BucketsDefinition.Linear</h2>
|
|
<section>
|
|
<p>Specifies a linear sequence of buckets that all have the same width
|
|
(except overflow and underflow). Each bucket represents a constant
|
|
absolute uncertainty on the specific value in the bucket.</p>
|
|
|
|
<p>There are <code>num_finite_buckets + 2</code> (= <code>N</code>) buckets. The two additional
|
|
buckets are the underflow and overflow buckets.</p>
|
|
|
|
<p>Bucket <code>i</code> has the following boundaries:</p>
|
|
|
|
<ul>
|
|
<li>Upper bound (<code>0 <= i < N-1</code>): <code>offset + (width * i)</code></li>
|
|
<li>Lower bound (<code>1 <= i < N</code>): <code>offset + (width * (i - 1))</code></li>
|
|
</ul>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Linear-num_finite_buckets">
|
|
<td><code>numFiniteBuckets</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Must be greater than 0.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Linear-width">
|
|
<td><code>width</code></td>
|
|
<td><code>double</code></td>
|
|
<td>
|
|
<p>Must be greater than 0.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-BucketsDefinition-Linear-offset">
|
|
<td><code>offset</code></td>
|
|
<td><code>double</code></td>
|
|
<td>
|
|
<p>Lower bound of the first bucket.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricInfo-Kind">Params.MetricInfo.Kind</h2>
|
|
<section>
|
|
<p>Describes what kind of metric this is.</p>
|
|
|
|
<table class="enum-values">
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricInfo-Kind-UNSPECIFIED">
|
|
<td><code>UNSPECIFIED</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-Kind-GAUGE">
|
|
<td><code>GAUGE</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-Kind-COUNTER">
|
|
<td><code>COUNTER</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricInfo-Kind-DISTRIBUTION">
|
|
<td><code>DISTRIBUTION</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="Params-MetricsExpirationPolicy">Params.MetricsExpirationPolicy</h2>
|
|
<section>
|
|
<p>Describes the expiration policy for metrics generated by a prometheus handler.</p>
|
|
|
|
<p>Example: A Metrics Expiration Policy of <code>{ metrics_expiry_duration: "10m", expiry_check_interval_duration: "1m" }</code>
|
|
would configure the handler to delete all metrics that have received no updtaes for 10 minutes. Metrics would be checked
|
|
every minute to determine whether or not they should be expired.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="Params-MetricsExpirationPolicy-metrics_expiry_duration">
|
|
<td><code>metricsExpiryDuration</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Required. Describes the desired lifetime of a metric. If the metric is not updated at any point during this duration, it
|
|
will be removed from the set of metrics exported by the handler.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="Params-MetricsExpirationPolicy-expiry_check_interval_duration">
|
|
<td><code>expiryCheckIntervalDuration</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Optional. Describes the interval in which metrics will be checked to see if they have been stale for longer that the configured
|
|
<code>metrics_expiry_duration</code>. This should be generally be set to a duration much shorter than the configured <code>metrics_expiry_duration</code>.
|
|
This bounds the total amount of additional time (beyond the desired lifetime) that a metric may be exported.
|
|
If a value is not explicitly provided, this value will default to half of the configured <code>metrics_expiry_duration</code>.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|