Monitor AKS applications with OTLP and Azure Monitor (Preview)

OpenTelemetry provides a standardized way to emit traces, logs, and metrics. Azure Monitor adds Preview support for monitoring applications that run on Azure Kubernetes Service (AKS) by using the OpenTelemetry Protocol (OTLP) for instrumentation and data collection.

Key capabilities

• Enable cluster-level monitoring to install Azure Monitor components on the AKS cluster.
• Create an Application Insights resource with OTLP ingestion enabled.
• Onboard applications at the namespace or deployment scope by using either:
  • Autoinstrumentation with the Azure Monitor OpenTelemetry distribution.
  • Autoconfiguration for applications already instrumented with the open-source OpenTelemetry Software Development Kits (SDKs).
    • Autoconfiguration applies only to applications that are already instrumented with OpenTelemetry. When you select autoconfiguration, Azure Monitor doesn't add instrumentation to your application. Instead, it sets environment variables at the platform level so existing OpenTelemetry SDKs export telemetry to Application Insights. You're responsible for instrumenting the application (for example, by using OpenTelemetry SDKs or annotations) before you enable autoconfiguration.

Telemetry flows to Application Insights, where you analyze application performance in context with Container Insights.

Roles and responsibilities

Use the following guidance to separate platform (cluster) responsibilities from application development (workload) responsibilities. Cluster administrator refers to the team that's responsible for the AKS cluster and Azure Monitor telemetry pipeline. Developer refers to the team that owns the application code and its telemetry configuration.

Out of scope for cluster admins: changing application code, selecting libraries, and defining business-level telemetry semantics.

Out of scope for developers: changing cluster add-ons, platform RBAC, shared ingestion resource topology, or cluster networking.

Common collaboration points:

• Agree on naming and labeling standards (service.name, k8s.deployment.name, and namespace conventions) so data is queryable and dashboards work across teams.
• Align on performance and cost guardrails (sampling strategy, log verbosity, and metric cardinality) and who changes what when limits are exceeded.
• Define a support workflow for telemetry issues (what developers check first vs. when to escalate to the cluster admin team).
• Plan changes jointly when they span both layers (for example, switching ingestion method, changing endpoint/temporality expectations, or introducing a collector).

Prerequisites

• An AKS cluster in Azure public cloud that runs at least one Kubernetes deployment.
• Azure CLI 2.78.0 or later. Install or update by using the guidance in Install the Azure CLI documentation.
  Verify the version:

  az version
  

• aks-preview Azure CLI extension:

  az extension add --name aks-preview
  az extension update --name aks-preview
  

1. Register the preview features

When you register the preview features, enable the feature flag on the subscription where you create the Application Insights resource and on the subscription that hosts the AKS cluster.

1. Sign in and select the target subscription:

   az login
   az account set --subscription "<subscription-name>"
   

2. Register the AKS preview feature and provider:

   az feature register --namespace "Microsoft.ContainerService" --name "AzureMonitorAppMonitoringPreview"
   az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/AzureMonitorAppMonitoringPreview')].{Name:name,State:properties.state}"
   az provider register --namespace "Microsoft.ContainerService"
   az provider show --namespace "Microsoft.ContainerService" --query "registrationState"
   

3. Register the Application Insights OTLP preview features and provider:

   az feature register --name OtlpApplicationInsights --namespace Microsoft.Insights
   az feature list -o table --query "[?contains(name, 'Microsoft.Insights/OtlpApplicationInsights')].{Name:name,State:properties.state}"
   
   az provider register -n Microsoft.Insights
   

2. Prepare the cluster

1. Ensure the cluster is onboarded to Azure Monitor metrics and logs. Use Enable monitoring for AKS clusters in Azure Monitor (Application Insights isn't required yet).
2. Turn on Enable support for Autoinstrumentation and Enable support for data collection from vendor neutral OpenTelemetry SDKs (Preview), and then select Review + enable.

If you didn't previously onboard the cluster, you can enable Managed Prometheus, Container Logs, and application monitoring at the same time.

3. Create an Application Insights resource with OTLP support

Create or select an Application Insights resource that supports OTLP and uses Managed workspaces.

1. In the Azure portal, create a new Application Insights resource.
2. Turn on Enable OTLP Support (Preview).
3. Set Use managed workspaces to Yes.
   

4. Onboard applications to Application Insights

You can onboard all deployments in a namespace or target individual deployments later.

4.1 Open the namespace

1. In the AKS resource, expand Kubernetes resources.
2. Open Namespaces, and then select the namespace that hosts your workloads.

4.2 Configure Application Monitoring (Preview)

When you enable OTLP, Application Insights adds support for open-source, vendor-neutral OpenTelemetry SDKs and OTLP endpoints, and stores metrics in an Azure Monitor workspace.

If you don't enable OTLP, Application Insights only uses Azure Monitor autoinstrumentation and classic ingestion.

1. Select Application Monitoring (Preview).
2. Choose the Application Insights resource with OTLP enabled that you created previously in step 3. If you select or create an Application Insights resource without OTLP by using the Create New option, you won't see the Instrumentation Type option in the next step.
3. Choose an Instrumentation Type:
   • User-configured instrumentation per deployment
     • Autoconfiguration sets environment variables so existing SDKs export telemetry to Application Insights
     • Each deployment must already have autoinstrumentation annotations or manual instrumentation. For more information, see Per deployment onboarding.
   • Java autoinstrumentation for all deployments for automatic injection of the Azure Monitor OpenTelemetry distribution into Java applications.
     • All deployments in the namespace use Java autoinstrumentation by default. Use annotations to change the language or exclude a deployment. For more information, see Automatic instrumentation and Per deployment onboarding.
   • NodeJs autoinstrumentation for all deployments for automatic injection of the Azure Monitor OpenTelemetry distribution into Node.js applications.
     • All deployments in the namespace use Node.js autoinstrumentation by default. Use annotations to change the language or exclude a deployment. For more information, see Automatic instrumentation and Per deployment onboarding.

   Note

   The Azure portal only allows you to apply autoinstrumentation OR autoconfiguration to a single namespace. If you need to use both options, see per-deployment onboarding options.

4. Leave Perform rollout restart of all deployments unchecked. You perform the restart manually in the next step.
5. Select Configure.
   

4.3 Restart deployments to apply changes

Restart deployments in the target namespace from Run command in the portal or from your terminal:

kubectl rollout restart deployment -n <your-namespace>

4.4 Confirm instrumented status

Return to Application Monitoring (Preview) for the namespace. Expand Deployments in this namespace and confirm that deployments show Instrumented status.

5. View application signals in Container Insights

Explore application performance in the context of your cluster by using Container Insights. From Monitor in the AKS resource, open Controllers and then select a controller to review request failures, slow operations, and suggested investigations.

To drill down to Container Insights, select an application component node in the Application Map.

Select the node and then Investigate Pods in the AKS monitoring tile.

Advanced onboarding (custom resources)

Use the Kubernetes custom resources when you need more control. For more information, see Per deployment onboarding.

Autoinstrumentation (Java, Node.js)

Follow the namespace-wide or per-deployment onboarding guidance in the article linked earlier to inject the Azure Monitor OpenTelemetry distribution into your pods.

To participate in the limited public preview of Autoinstrumentation for .NET or Python, see Enable AKS autoinstrumentation for Python and .NET (limited preview).

Autoconfiguration (apps already instrumented with OpenTelemetry SDKs)

Autoconfiguration sets environment variables so existing SDKs export telemetry to Application Insights through the Azure Monitor Agent on the cluster. It doesn't place any SDK on the pod.

• Namespace-wide: Set the Instrumentation custom resource with an empty platforms list.

  apiVersion: monitor.azure.com/v1
  kind: Instrumentation
  metadata:
    name: cr1
    namespace: mynamespace1
  spec:
    settings:
      autoInstrumentationPlatforms: []
    destination: # required
      applicationInsightsConnectionString: "InstrumentationKey=11111111-1111-1111-1111-111111111111;IngestionEndpoint=https://eastus2-3.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus2.livediagnostics.monitor.azure.com/"
  

• Per-deployment: Add the annotation to the deployment and reference your instrumentation custom resource (replace cr1 with your resource name).

  apiVersion: apps/v1
  kind: Deployment
  ...
  spec:
    template:
      metadata:
        annotations:
          instrumentation.opentelemetry.io/inject-nodejs: "cr1"
  

When you use the inject-configuration annotation, the spec.settings.autoInstrumentationPlatforms setting on the referenced custom resource is ignored and the deployment is configured to send OTLP data to the connection string defined in applicationInsightsConnectionString. Use the annotation value "false" to exclude a deployment from Autoconfiguration.

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-nodejs: "false"

Limitations

During the preview, the feature is available in all public cloud regions except:

• Israel Central
• Israel North West
• Qatar Central
• UAE North
• UAE Central

If you need programmatic names for these regions, see Azure regions list.

Limits

• The feature accepts only OTLP/HTTP with binary Protobuf. It doesn't support JSON payloads or OTLP/gRPC. You need to configure your OTLP exporter accordingly when using autoconfiguration with the open-source, vendor-neutral SDKs.
• The feature supports up to 30 Data Collection Rule (DCR) associations per AKS cluster.
• The tested scale for logs and traces is 50,000 events per second (EPS). You can expect approximately 250 MiB extra memory usage and 0.5 vCPU per cluster for this feature.

Unsupported scenarios

• Compression in OpenTelemetry SDK exporters.
• Namespaces with Istio mutual TLS (mTLS) enabled.
• HTTPS endpoints in the instrumentation configuration.

Scenarios not validated

• AKS clusters that use an HTTP proxy.
• AKS clusters that use Private Link.
• AKS dual-stack clusters.

Next steps

• Learn how codeless instrumentation works for Kubernetes and how to onboard deployments.
• Review the Enable monitoring for AKS clusters article to understand infrastructure monitoring with Azure Monitor.
• Learn to configure application monitoring with Azure Monitor and OTLP for other environments with the Azure Monitor Agent or the open-source OpenTelemetry Collector.

Support

If documentation and the steps in this article don't resolve your issue or you want to provide feedback, email the Azure Monitor OpenTelemetry team at otel@microsoft.com.