> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Azuremonitor

> OpenTelemetry exporter for Azuremonitor

# Azuremonitor Exporter

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@pcwiese](https://github.com/pcwiese), [@hgaol](https://github.com/hgaol)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/azuremonitorexporter)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-beta-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ![Traces](https://img.shields.io/badge/traces-beta-orange)

## Overview

This exporter sends logs, traces and metrics to [Azure Monitor](https://docs.microsoft.com/azure/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](https://docs.microsoft.com/azure/azure-monitor/app/create-new-resource) and [find your connection string](https://docs.microsoft.com/azure/azure-monitor/app/sdk-connection-string?tabs=net#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
* `shutdown_timeout` (default = 1s): Timeout to wait for graceful shutdown. Once exceeded, the component will shut down forcibly, dropping any element in queue.
* `custom_events_enabled` (default = `false`): Enables export log record to custom events when there's attribute `microsoft.custom_event.name` or `APPLICATION_INSIGHTS_EVENT_MARKER_ATTRIBUTE`.

### Tag mappings (alpha)

The optional `tag_mappings:` block overrides how selected Application Insights envelope tags are populated from OpenTelemetry resource attributes. Each field takes an ordered list of sources; the first one that resolves to a non-empty string wins.

A source entry is interpreted as:

* a **resource attribute key** when it contains a `.` (e.g. `service.instance.id`, `host.name`)
* a **string literal terminal default** when it does not contain a `.` (e.g. `unknown-instance`)

Defaults preserve the historical hardcoded behavior — when a field is unset, zero-config users see no change.

| Mapping key           | Application Insights tag | Default                 |
| --------------------- | ------------------------ | ----------------------- |
| `cloud_role_instance` | `ai.cloud.roleInstance`  | `[service.instance.id]` |
| `application_version` | `ai.application.ver`     | `[service.version]`     |

> The `cloud_role_name` tag (`ai.cloud.role`) is not yet configurable; its hardcoded `service.namespace`/`service.name` concatenation continues to apply.

Example — Azure Container Apps, where `service.instance.id` is set to a random uuid and operators want the revision/replica hostname instead:

```yaml theme={null}
exporters:
  azuremonitor:
    connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/"
    tag_mappings:
      cloud_role_instance: [host.name, service.instance.id, unknown-instance]
```

Validation rejects an explicitly empty array (`cloud_role_instance: []`) at startup. The feature is alpha and the schema may evolve.

Example:

```yaml theme={null}

# 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)

```yaml theme={null}
# 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:

```yaml theme={null}
exporters:
  azuremonitor:
```

## Attribute mapping

### Traces

This exporter maps OpenTelemetry trace data to [Application Insights data model](https://docs.microsoft.com/azure/azure-monitor/app/data-model-dependency-telemetry) 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 in [trace\_to\_envelope.go](trace_to_envelope.go).

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

All links are mapped to property `_MS.links` with JSON array string.

#### 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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-traceid) is mapped to `operation_id` column and [SpanId](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-spanid) is mapped to `operation_parentId` column.

#### Custom Events

When `custom_events_enabled` = `true`, azure monitor exporter will export log record to custom events when there's attribute `microsoft.custom_event.name` or `APPLICATION_INSIGHTS_EVENT_MARKER_ATTRIBUTE`.

#### Exceptions

This exporter saves exception records to Application Insights `exceptions` table when log records indicate an exception [specification](https://opentelemetry.io/docs/specs/otel/trace/exceptions/).

When `exception_events_enabled` = `true`, azure monitor exporter will export log records to exceptions when either one of `exception.message` or `exception.type` attributes are set.

### 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](AUTHENTICATION.md) page.

## Configuration

### Example Configuration

```yaml theme={null}
azuremonitor:
azuremonitor/2:
  # endpoint is the uri used to communicate with Azure Monitor
  endpoint: "https://dc.services.visualstudio.com/v2/track"
  # instrumentation_key is the unique identifier for your Application Insights resource
  instrumentation_key: 00000000-0000-0000-0000-000000000000
  # connection string specifies Application Insights InstrumentationKey and IngestionEndpoint
  connection_string: InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/
  # maxbatchsize is the maximum number of items that can be queued before calling to the configured endpoint
  maxbatchsize: 100
  # maxbatchinterval is the maximum time to wait before calling the configured endpoint.
  maxbatchinterval: 10s
  # shutdown channel timeout
  shutdown_timeout: 2s

  sending_queue:
    # queue_size is the maximum number of items that can be queued before dropping data
    queue_size: 1000
    enabled: true
    num_consumers: 10
    storage: disk

azuremonitor/tag_mappings:
  connection_string: InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/
  tag_mappings:
    cloud_role_instance: [host.name, service.instance.id, unknown-instance]
    application_version: [service.version]

disk/3:
```

***

*Last generated: 2026-07-06*