azuremonitorexporter

README

Azure Monitor Exporter

Status
Stability	beta: traces, metrics, logs
Distributions	contrib
Issues
Code Owners	@pcwiese

This exporter sends logs, traces and metrics to Azure Monitor.

Configuration

To configure the Azure Monitor Exporter, you must specify one of the following settings:

• connection_string (recommended): The Azure Application Insights Connection String is required to send telemetry data to the monitoring service. It is the recommended method for configuring the exporter, aligning with Azure Monitor's best practices. If you need guidance on creating Azure resources, please refer to the step-by-step guides to Create an Application Insights resource and find your connection string.
• instrumentation_key: Application Insights instrumentation key, which can be found in the Application Insights resource in the Azure Portal. While it is currently supported, its use is discouraged and it is slated for deprecation. It is highly encouraged to use the connection_string setting for new configurations and migrate existing configurations to use the connection_string as soon as possible.

Environment Variable Support

In addition to the above configuration options, the Azure Monitor Exporter now supports setting the connection string via the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable. This method is particularly useful for cloud or containerized environments where managing configuration through environment variables is standard practice.

Note: If both the environment variable and the connection_string configuration option are provided, the environment variable takes precedence.

Configuration Options

Important: Only one of connection_string or instrumentation_key should be specified in your configuration. If both are provided, connection_string will be used as the priority setting.

The following settings can be optionally configured:

• endpoint (default = https://dc.services.visualstudio.com/v2/track): The endpoint URL where data will be submitted. While this option remains available, it is important to note that the use of the connection_string is recommended, as it encompasses the endpoint information. The direct configuration of the endpoint is considered to be on a deprecation path.
• maxbatchsize (default = 1024): The maximum number of telemetry items that can be submitted in each request. If this many items are buffered, the buffer will be flushed before maxbatchinterval expires.
• maxbatchinterval (default = 10s): The maximum time to wait before sending a batch of telemetry.
• spaneventsenabled (default = false): Enables export of span events.
• sending_queue
  • enabled (default = false)
  • num_consumers (default = 10): Number of consumers that dequeue batches; ignored if enabled is false
  • queue_size (default = 1000): Maximum number of batches kept in memory before data; ignored if enabled is false
  • storage (default = none): When set, enables persistence and uses the component specified as a storage extension for the persistent queue

Example:

# Recommended Configuration:
# It is highly recommended to use the connection string which includes the InstrumentationKey and IngestionEndpoint
# This is the preferred method over using 'instrumentation_key' alone.
exporters:
  azuremonitor:
    connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/"

(or)

# Legacy Configuration:
# The use of 'instrumentation_key' alone is not recommended and will be deprecated in the future. It is advised to use the connection_string instead.
# This example is provided primarily for existing configurations that have not yet transitioned to the connection string.
exporters:
  azuremonitor:
    instrumentation_key: b1cd0778-85fc-4677-a3fa-79d3c23e0efd

Example using environment variable:

Ensure APPLICATIONINSIGHTS_CONNECTION_STRING is set in your environment, then configure the exporter without specifying a connection string or instrumentation key:

exporters:
  azuremonitor:

Attribute mapping

Traces

This exporter maps OpenTelemetry trace data to Application Insights data model using the following schema.

The OpenTelemetry SpanKind determines the Application Insights telemetry type.

OpenTelemetry SpanKind	Application Insights telemetry type
CLIENT, PRODUCER, INTERNAL	Dependency
SERVER, CONSUMER	Request

The exporter follows the semantic conventions to fill the Application Insights specific telemetry properties. The following table shows a basic mapping.

Application Insights property	OpenTelemetry attribute	Default
Request.Name	http.method, http.route or rpc.system	span name
Request.Url	http.scheme, http.host, http.target
Request.Source	http.client_ip or net.peer.name
Request.ResponseCode	http.status_code or status_code	"0"
Request.Success	http.status_code or status_code	true
Dependency.Name	http.method, http.route	span name
Dependency.Data	http.url or span name or db.statement
Dependency.Type	"HTTP" or rpc.system or db.system or "InProc"
Dependency.Target	host of http.url or net.peer.name
Dependency.ResultCode	http.status_code or status_code	"0"
Dependency.Success	http.status_code or status_code	true

The exact mapping can be found here.

All attributes are also mapped to custom properties if they are booleans or strings and to custom measurements if they are ints or doubles.

Span Events

Span events are optionally saved to the Application Insights traces table. Exception events are saved to the Application Insights exception table.

Logs

This exporter saves log records to Application Insights traces table. TraceId is mapped to operation_id column and SpanId is mapped to operation_parentId column.

Metrics

This exporter saves metrics to Application Insights customMetrics table.

AAD/Entra Authentication

Details of how to use the Azure Monitor Exporter with AAD/Entra based identities can be found in the Authentication page.

Documentation

Index

• Constants
• func NewFactory() exporter.Factory
• type Config
• type ConnectionVars
• type DatabaseAttributes
  • func (attrs *DatabaseAttributes) MapAttribute(k string, v pcommon.Value) bool
• type ExceptionAttributes
  • func (attrs *ExceptionAttributes) MapAttribute(k string, v pcommon.Value) bool
• type HTTPAttributes
  • func (attrs *HTTPAttributes) MapAttribute(k string, v pcommon.Value) bool
• type MessagingAttributes
  • func (attrs *MessagingAttributes) MapAttribute(k string, v pcommon.Value) bool
• type NetworkAttributes
  • func (attrs *NetworkAttributes) MapAttribute(k string, v pcommon.Value) bool
• type RPCAttributes
  • func (attrs *RPCAttributes) MapAttribute(k string, v pcommon.Value) bool
• type TraceVisitor

Constants

const (
	ApplicationInsightsConnectionString = "APPLICATIONINSIGHTS_CONNECTION_STRING"
	DefaultIngestionEndpoint            = "https://dc.services.visualstudio.com/"
	IngestionEndpointKey                = "IngestionEndpoint"
	InstrumentationKey                  = "InstrumentationKey"
	ConnectionStringMaxLength           = 4096
)

Functions

func NewFactory

func NewFactory() exporter.Factory

NewFactory returns a factory for Azure Monitor exporter.

Types

type Config

type Config struct {
	QueueSettings      exporterhelper.QueueConfig `mapstructure:"sending_queue"`
	Endpoint           string                     `mapstructure:"endpoint"`
	ConnectionString   configopaque.String        `mapstructure:"connection_string"`
	InstrumentationKey configopaque.String        `mapstructure:"instrumentation_key"`
	MaxBatchSize       int                        `mapstructure:"maxbatchsize"`
	MaxBatchInterval   time.Duration              `mapstructure:"maxbatchinterval"`
	SpanEventsEnabled  bool                       `mapstructure:"spaneventsenabled"`
}

Config defines configuration for Azure Monitor

type ConnectionVars

type ConnectionVars struct {
	InstrumentationKey string
	IngestionURL       string
}

type DatabaseAttributes

type DatabaseAttributes struct {
	DBSystem              string
	DBConnectionString    string
	DBUser                string
	DBName                string
	DBStatement           string
	DBOperation           string
	DBMSSQLInstanceName   string
	DBJDBCDriverClassName string
	DBCassandraKeyspace   string
	DBHBaseNamespace      string
	DBRedisDatabaseIndex  string
	DBMongoDBCollection   string
	NetworkAttributes     NetworkAttributes
}

DatabaseAttributes is the set of known attributes for Database Spans

func (*DatabaseAttributes) MapAttribute

func (attrs *DatabaseAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a Span attribute to one of the known types

type ExceptionAttributes

type ExceptionAttributes struct {
	ExceptionEscaped    string
	ExceptionMessage    string
	ExceptionStackTrace string
	ExceptionType       string
}

ExceptionAttributes is the set of known attributes for Exception events

func (*ExceptionAttributes) MapAttribute

func (attrs *ExceptionAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a SpanEvent attribute to one of the known types

type HTTPAttributes

type HTTPAttributes struct {
	// common attributes
	// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#common-attributes
	HTTPMethod                            string
	HTTPURL                               string
	HTTPTarget                            string
	HTTPHost                              string
	HTTPScheme                            string
	HTTPStatusCode                        int64
	HTTPStatusText                        string
	HTTPFlavor                            string
	HTTPUserAgent                         string
	HTTPRequestContentLength              int64
	HTTPRequestContentLengthUncompressed  int64
	HTTPResponseContentLength             int64
	HTTPResponseContentLengthUncompressed int64

	// Server Span specific
	// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-server-semantic-conventions
	HTTPRoute      string
	HTTPServerName string
	HTTPClientIP   string

	// any net.*
	NetworkAttributes NetworkAttributes
}

HTTPAttributes is the set of known attributes for HTTP Spans

func (*HTTPAttributes) MapAttribute

func (attrs *HTTPAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a Span attribute to one of the known types

type MessagingAttributes

type MessagingAttributes struct {
	MessagingSystem                       string
	MessagingDestination                  string
	MessagingDestinationKind              string
	MessagingTempDestination              string
	MessagingProtocol                     string
	MessagingProtocolVersion              string
	MessagingURL                          string
	MessagingMessageID                    string
	MessagingConversationID               string
	MessagingMessagePayloadSize           int64
	MessagingMessagePayloadCompressedSize int64
	MessagingOperation                    string
	NetworkAttributes                     NetworkAttributes
}

MessagingAttributes is the set of known attributes for Messaging Spans

func (*MessagingAttributes) MapAttribute

func (attrs *MessagingAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a Span attribute to one of the known types

type NetworkAttributes

type NetworkAttributes struct {
	// see https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/network.md#network-attributes
	NetTransport string
	NetPeerIP    string
	NetPeerPort  int64
	NetPeerName  string
	NetHostIP    string
	NetHostPort  int64
	NetHostName  string
}

NetworkAttributes is the set of known network attributes

func (*NetworkAttributes) MapAttribute

func (attrs *NetworkAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a Span attribute to one of the known types

type RPCAttributes

type RPCAttributes struct {
	RPCSystem         string
	RPCService        string
	RPCMethod         string
	RPCGRPCStatusCode int64
	NetworkAttributes NetworkAttributes
}

RPCAttributes is the set of known attributes for RPC Spans

func (*RPCAttributes) MapAttribute

func (attrs *RPCAttributes) MapAttribute(k string, v pcommon.Value) bool

MapAttribute attempts to map a Span attribute to one of the known types

type TraceVisitor

type TraceVisitor interface {
	// contains filtered or unexported methods
}

TraceVisitor interface defines a iteration callback when walking through traces