Skill

Pass

Audit score 90

observability-edot-dotnet-migrate

elastic/agent-skills

Migrate .NET applications from classic Elastic APM agent to EDOT .NET SDK

What is observability-edot-dotnet-migrate?

Guides migration of .NET applications from Elastic.Apm.* packages to Elastic.OpenTelemetry. Use this when switching to the modern OpenTelemetry-based observability approach for .NET applications.

Remove classic Elastic APM NuGet packages and configuration references
Add Elastic.OpenTelemetry and OpenTelemetry.Instrumentation.AspNetCore packages
Register EDOT in application startup via AddElasticOpenTelemetry()
Configure required environment variables (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS)
Validate endpoint configuration to use managed OTLP or EDOT Collector URLs

How to install observability-edot-dotnet-migrate

npx skills add https://github.com/elastic/agent-skills --skill observability-edot-dotnet-migrate

Prerequisites

Existing .NET application using classic Elastic.Apm.* packages
Access to Elastic observability platform or EDOT Collector endpoint
NuGet package management configured

Claude Code

Cursor

Windsurf

Cline

How to use observability-edot-dotnet-migrate

1.Read the official EDOT .NET migration guide from Elastic documentation
2.Remove all Elastic.Apm.* NuGet packages from your project
3.Remove UseAllElasticApm() or AddAllElasticApm() calls from Program.cs or startup code
4.Remove ElasticApm section from appsettings.json and all ELASTIC_APM_* environment variables
5.Add NuGet packages: Elastic.OpenTelemetry and OpenTelemetry.Instrumentation.AspNetCore (for ASP.NET Core)
6.Call builder.AddElasticOpenTelemetry() in Program.cs on the IHostApplicationBuilder
7.Set three required environment variables: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT (use managed OTLP or EDOT Collector URL, not APM Server), and OTEL_EXPORTER_OTLP_HEADERS with authentication
8.Test application startup and verify telemetry is being collected in Elastic observability platform

Use cases

Good for

Upgrading a .NET Framework or .NET Core application to use modern OpenTelemetry-based observability
Consolidating observability across polyglot environments using standard OTLP protocol
Migrating from legacy Elastic APM Server integration to managed Elastic observability
Enabling traces, metrics, and logs collection through a single unified SDK

Who it's for

Backend engineers maintaining .NET applications
DevOps engineers managing observability infrastructure
Teams migrating to OpenTelemetry standards

observability-edot-dotnet-migrate FAQ

Can I run both classic Elastic APM and EDOT on the same application?

No. Never run both the classic Elastic APM agent (Elastic.Apm.*) and EDOT on the same application simultaneously.

What should I use for OTEL_EXPORTER_OTLP_ENDPOINT?

Use the managed OTLP endpoint or EDOT Collector URL. Do NOT reuse the old ELASTIC_APM_SERVER_URLS value or APM Server URLs (which contain apm-server, :8200, or /intake/v2/events).

Do I need to set OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, or OTEL_LOGS_EXPORTER?

No. Do not set these variables—the defaults in EDOT .NET are already correct.

What replaces ELASTIC_APM_SERVICE_NAME?

Use OTEL_SERVICE_NAME environment variable instead.

What replaces ELASTIC_APM_SECRET_TOKEN?

Use OTEL_EXPORTER_OTLP_HEADERS with value 'Authorization=ApiKey <key>' or 'Authorization=Bearer <token>'.

Full instructions (SKILL.md)

Source of truth, from elastic/agent-skills.

name: observability-edot-dotnet-migrate description: > Migrate a .NET application from the classic Elastic APM .NET agent to the EDOT .NET SDK. Use when switching from Elastic.Apm.* packages to Elastic.OpenTelemetry. metadata: author: elastic version: 0.1.0

EDOT .NET Migration

Read the migration guide before making changes:

Guidelines

Remove ALL classic APM references: Elastic.Apm.* NuGet packages (including Elastic.Apm.NetCoreAll), UseAllElasticApm() / AddAllElasticApm() calls, the ElasticApm section from appsettings.json, and all ELASTIC_APM_* env vars
Add NuGet packages: Elastic.OpenTelemetry and OpenTelemetry.Instrumentation.AspNetCore (for ASP.NET Core apps)
Register EDOT in startup: call builder.AddElasticOpenTelemetry() on the IHostApplicationBuilder (in Program.cs or equivalent). Without this, no telemetry is collected
Set exactly three required environment variables:
- OTEL_SERVICE_NAME (replaces ELASTIC_APM_SERVICE_NAME / ElasticApm:ServiceName)
- OTEL_EXPORTER_OTLP_ENDPOINT — must be the managed OTLP endpoint or EDOT Collector URL. Do NOT reuse the old ELASTIC_APM_SERVER_URLS value. Never use an APM Server URL (no apm-server, no :8200, no /intake/v2/events)
- OTEL_EXPORTER_OTLP_HEADERS — "Authorization=ApiKey <key>" or "Authorization=Bearer <token>" (replaces ELASTIC_APM_SECRET_TOKEN)
Do NOT set OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, or OTEL_LOGS_EXPORTER — the defaults are already correct
Never run both classic Elastic APM agent (Elastic.Apm.*) and EDOT on the same application

Examples

See the EDOT .NET migration guide for complete examples.

Related skills

More from elastic/agent-skills and the wider catalog.

observability-edot-java-instrument

elastic/agent-skills

Instrument Java applications with Elastic's OpenTelemetry agent for automatic tracing, metrics, and logs.

1.4k installs

observability-edot-java-migrate

elastic/agent-skills

Migrate Java applications from classic Elastic APM agent to EDOT Java agent.

1.4k installs

observability-edot-python-instrument

elastic/agent-skills

Instrument Python apps with Elastic Distribution of OpenTelemetry for automatic tracing, metrics, and logs.

1.4k installs

observability-edot-python-migrate

elastic/agent-skills

Migrate Python applications from classic Elastic APM agent to EDOT Python agent.

1.4k installs

observability-k8s-investigation

elastic/agent-skills

664 installs

observability-llm-obs

elastic/agent-skills

Monitor LLM performance, cost, tokens, and agentic workflows in Elastic.

1.5k installs