Prometheus

The prometheus adapter collects Istio metrics and makes them available toPrometheus.

This adapter supports the metric template.

Params

Configuration format for the prometheus adapter.

FieldTypeDescriptionRequired
metricsMetricInfo[]The set of metrics to represent in Prometheus. If a metric is defined in Istio but doesn’t have a correspondingshape here, it will not be populated at runtime.No
metricsExpirationPolicyMetricsExpirationPolicyOptional. The rate at which to expire metrics from the adapter. This option controls the amount of metric datathat the adapter will maintain over its lifetime.EXPERIMENTAL: This feature should only be used in advanced cases.Example config stanza:
  1. metricsExpirationPolicy: metricsExpiryDuration: "5s" expiryCheckIntervalDuration: "1s"
No

Params.MetricInfo

Describes how a metric should be represented in Prometheus.

FieldTypeDescriptionRequired
namespacestringOptional. The namespace is used as a prefix on the metric names.An example: for a metric named requests_total with a namespace of istio,the full metric name becomes istio_requests_total.NOTE: The specified namespace should be a prometheus-safe name. If not, the adapterwill attempt to convert the namespace to a prometheus-safe name.NOTE: Changing the value for this will potentially impact downstream integrationsand should be used with caution.Default value: istio.No
namestringRecommended. 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.No
instanceNamestringRequired. The name is the fully qualified name of the Istio metric instancethat this MetricInfo processes.No
descriptionstringOptional. A human readable description of this metric.No
kindKindNo
bucketsBucketsDefinitionFor metrics with a metric kind of DISTRIBUTION, this provides a mechanismfor 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.No
labelNamesstring[]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.No

Params.MetricInfo.BucketsDefinition

Describes buckets for DISTRIBUTION kind metrics.

FieldTypeDescriptionRequired
linearBucketsLinear (oneof)The linear buckets.Yes
exponentialBucketsExponential (oneof)The exponential buckets.Yes
explicitBucketsExplicit (oneof)The explicit buckets.Yes

Params.MetricInfo.BucketsDefinition.Explicit

Specifies a set of buckets with arbitrary widths.

There are size(bounds) + 1 (= N) buckets. Bucket i has the followingboundaries:

  • Upper bound (0 <= i < N-1): bounds[i]
  • Lower bound (1 <= i < N): bounds[i - 1]

The bounds field must contain at least one element. If bounds hasonly one element, then there are no finite buckets, and that singleelement is the common boundary of the overflow and underflow buckets.

FieldTypeDescriptionRequired
boundsdouble[]The values must be monotonically increasing.No

Params.MetricInfo.BucketsDefinition.Exponential

Specifies an exponential sequence of buckets that have a width that isproportional to the value of the lower bound. Each bucket represents aconstant relative uncertainty on a specific value in the bucket.

There are num_finite_buckets + 2 (= N) buckets. The two additionalbuckets are the underflow and overflow buckets.

Bucket i has the following boundaries:

  • Upper bound (0 <= i < N-1): scale * (growth_factor ^ i)
  • Lower bound (1 <= i < N): scale * (growth_factor ^ (i - 1))
FieldTypeDescriptionRequired
numFiniteBucketsint32Must be greater than 0.No
growthFactordoubleMust be greater than 1.No
scaledoubleMust be greater than 0.No

Params.MetricInfo.BucketsDefinition.Linear

Specifies a linear sequence of buckets that all have the same width(except overflow and underflow). Each bucket represents a constantabsolute uncertainty on the specific value in the bucket.

There are num_finite_buckets + 2 (= N) buckets. The two additionalbuckets are the underflow and overflow buckets.

Bucket i has the following boundaries:

  • Upper bound (0 <= i < N-1): offset + (width * i)
  • Lower bound (1 <= i < N): offset + (width * (i - 1))
FieldTypeDescriptionRequired
numFiniteBucketsint32Must be greater than 0.No
widthdoubleMust be greater than 0.No
offsetdoubleLower bound of the first bucket.No

Params.MetricInfo.Kind

Describes what kind of metric this is.

NameDescription
UNSPECIFIED
GAUGE
COUNTER
DISTRIBUTION

Params.MetricsExpirationPolicy

Describes the expiration policy for metrics generated by a prometheus handler.

Example: A Metrics Expiration Policy of { metrics_expiry_duration: "10m", expiry_check_interval_duration: "1m" }would configure the handler to delete all metrics that have received no updtaes for 10 minutes. Metrics would be checkedevery minute to determine whether or not they should be expired.

FieldTypeDescriptionRequired
metricsExpiryDurationDurationRequired. Describes the desired lifetime of a metric. If the metric is not updated at any point during this duration, itwill be removed from the set of metrics exported by the handler.No
expiryCheckIntervalDurationDurationOptional. Describes the interval in which metrics will be checked to see if they have been stale for longer that the configuredmetrics_expiry_duration. This should be generally be set to a duration much shorter than the configured metrics_expiry_duration.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 metrics_expiry_duration.No