prometheusexporter

README

Prometheus Exporter

Status
Stability	beta: metrics
Distributions	core, contrib
Issues
Code coverage
Code Owners	@Aneurysm9, @dashpole, @ArthurSens

Exports data in the Prometheus format, which allows it to be scraped by a Prometheus server.

Getting Started

The following settings are required:

• endpoint (no default): the address on which metrics will be exposed, using path /metrics. For more info, see the full list of ServerConfig options.

The following settings can be optionally configured:

• const_labels (no default): key/values that are applied for every exported metric.
• namespace (no default): if set, exports metrics under the provided value.
• send_timestamps (default = false): if true, sends the timestamp of the underlying metric sample in the response.
• metric_expiration (default = 5m): defines how long metrics are exposed without updates
• resource_to_telemetry_conversion
  • enabled (default = false): If enabled is true, all the resource attributes will be converted to metric labels by default.
• enable_open_metrics: (default = false): If true, metrics will be exported using the OpenMetrics format. Exemplars are only exported in the OpenMetrics format, and only for histogram and monotonic sum (i.e. counter) metrics.
• without_scope_info: (default = false): If true, metrics will be exported without scope name, version, schemaURL, and attributes encoded as labels.
• add_metric_suffixes: (default = true): If false, addition of type and unit suffixes is disabled. Deprecated: Use translation_strategy instead. This setting is ignored when translation_strategy is explicitly set.
• translation_strategy: Controls how OTLP metric and attribute names are translated into Prometheus metric and label names. When set, this takes precedence over add_metric_suffixes. Available options:
  • UnderscoreEscapingWithSuffixes: Fully escapes metric names for classic Prometheus metric name compatibility, and includes appending type and unit suffixes.
  • UnderscoreEscapingWithoutSuffixes: Metric names will continue to escape special characters to _, but suffixes won't be attached.
  • NoUTF8EscapingWithSuffixes: Disables changing special characters to _. Special suffixes like units and _total for counters will be attached.
  • NoTranslation: Bypasses all metric and label name translation, passing them through unaltered.

Example:

exporters:
  prometheus:
    endpoint: "1.2.3.4:1234"
    tls:
      ca_file: "/path/to/ca.pem"
      cert_file: "/path/to/cert.pem"
      key_file: "/path/to/key.pem"
    namespace: test-space
    const_labels:
      label1: value1
      "another label": spaced value
    send_timestamps: true
    metric_expiration: 180m
    enable_open_metrics: true
    # Legacy configuration - deprecated, ignored when translation_strategy is set
    add_metric_suffixes: false
    translation_strategy: "UnderscoreEscapingWithoutSuffixes"
    resource_to_telemetry_conversion:
      enabled: true

Given the example, metrics will be available at https://1.2.3.4:1234/metrics.

Feature gates

There are also flags that control translation behavior. See the documentation for the Prometheus translator module for more information.

Metric names and labels normalization

By Default, OpenTelemetry metric names and attributes are normalized to be compliant with Prometheus naming rules.

Optionally, users can set different translation_strategy options to control how metrics are exposed. Please be aware that Prometheus itself uses content negotiation to decide how to ingest metrics, and underscore escaping might be applied even though this exporter is configured to keep UTF-8 characters. For more details, read Prometheus' Content Negotiation documentation.

Setting resource attributes as metric labels

By default, resource attributes are added to a special metric called target_info. To select and group by metrics by resource attributes, you need to do join on target_info. For example, to select metrics with k8s_namespace_name attribute equal to my-namespace:

app_ads_ad_requests_total * on (job, instance) group_left target_info{k8s_namespace_name="my-namespace"}

Or to group by a particular attribute (for ex. k8s_namespace_name):

sum by (k8s_namespace_name) (app_ads_ad_requests_total * on (job, instance) group_left(k8s_namespace_name) target_info)

This is not a common pattern, and we recommend copying the most common resource attributes into metric labels. You can do this through the transform processor:

processor:
  transform:
    metric_statements:
      - context: datapoint
        statements:
        - set(attributes["namespace"], resource.attributes["k8s.namespace.name"])
        - set(attributes["container"], resource.attributes["k8s.container.name"])
        - set(attributes["pod"], resource.attributes["k8s.pod.name"])

After this, grouping or selecting becomes as simple as:

app_ads_ad_requests_total{namespace="my-namespace"}

sum by (namespace) (app_ads_ad_requests_total)

Documentation

Overview

Package prometheusexporter exports metrics data as a Prometheus pull handler.

Index

• func NewFactory() exporter.Factory
• type Config
  • func (cfg *Config) Validate() error

Functions

func NewFactory

func NewFactory() exporter.Factory

NewFactory creates a new Prometheus exporter factory.

Types

type Config

type Config struct {
	confighttp.ServerConfig `mapstructure:",squash"`

	// QueueBatchConfig defines the queue configuration.
	QueueBatchConfig configoptional.Optional[exporterhelper.QueueBatchConfig] `mapstructure:"sending_queue"`

	// Namespace if set, exports metrics under the provided value.
	Namespace string `mapstructure:"namespace"`

	// ConstLabels are values that are applied for every exported metric.
	ConstLabels prometheus.Labels `mapstructure:"const_labels"`

	// SendTimestamps will send the underlying scrape timestamp with the export
	SendTimestamps bool `mapstructure:"send_timestamps"`

	// MetricExpiration defines how long metrics are kept without updates
	MetricExpiration time.Duration `mapstructure:"metric_expiration"`

	// ResourceToTelemetrySettings defines configuration for converting resource attributes to metric labels.
	ResourceToTelemetrySettings resourcetotelemetry.Settings `mapstructure:"resource_to_telemetry_conversion"`

	// EnableOpenMetrics enables the use of the OpenMetrics encoding option for the prometheus exporter.
	EnableOpenMetrics bool `mapstructure:"enable_open_metrics"`

	// WithoutScopeInfo controls the addition of labels for the instrumentation scope.
	WithoutScopeInfo bool `mapstructure:"without_scope_info"`

	// AddMetricSuffixes controls whether suffixes are added to metric names. Defaults to true.
	//
	// Deprecated: Use TranslationStrategy instead. This setting is ignored when TranslationStrategy is explicitly set.
	AddMetricSuffixes bool `mapstructure:"add_metric_suffixes"`

	// TranslationStrategy controls how OTLP metric and attribute names are translated into Prometheus metric and label names.
	// When set, this takes precedence over AddMetricSuffixes.
	TranslationStrategy translationStrategy `mapstructure:"translation_strategy"`
}

Config defines configuration for Prometheus exporter.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks if the exporter configuration is valid