Documentation

SkyAPM-dotnet is a community, open-source .NET auto-instrumentation agent for the .NET ecosystem. It provides distributed tracing, application topology, metrics, and log correlation for ASP.NET Core and .NET hosted applications, and reports the collected telemetry to an Apache SkyWalking backend. It is an independent project, not an Apache Software Foundation or SkyWalking sub-project.

The agent targets net8.0 and net10.0 (the active .NET LTS releases); foundational libraries also build for netstandard2.0. Apps on newer runtimes (e.g. net9.0) are covered via the net8.0 assemblies. The current version is 2.3.0.

This agent speaks the SkyWalking v8 protocol and propagates context with the sw8 trace header only. By default the agent reports over gRPC to the OAP server on port 11800 (the SkyWalking query API and UI use 12800 / 8080).

Getting Started

Getting Started — install the agent, point it at an OAP server, and see your first trace.

Installation & Activation

Installation & Activation — NuGet packages (SkyAPM.Agent.AspNetCore, SkyAPM.Agent.GeneralHost), zero-code activation via ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, and how to set the service name.

Configuration

Configuration Reference — every option in skyapm.json, configuration sources and override order, and environment-variable mapping.
配置参考（中文） — Chinese translation of the configuration reference.

Transports

Transports (gRPC & Kafka) — choose and configure the gRPC reporter (default, port 11800) or the Kafka reporter, including topic names and timeouts.

Plugins / Supported Components

Plugins & Supported Components — how diagnostic plugins are wired in and which packages enable each integration.
Supported middlewares, frameworks and libraries — the authoritative list of instrumented components.

Logging

Logging — the agent’s internal log file, log level, rolling/retention options, and log-data reporting to OAP.

CLI

CLI (SkyAPM.DotNet.CLI) — the dotnet skyapm config tool that generates a skyapm.json for the gRPC or Kafka reporter.

Troubleshooting

Troubleshooting — diagnosing missing traces, no connection to OAP, the agent no-op conditions, and where to look in the logs.

How to Build

How to Build — compile the agent from source, including the Git submodule and protocol-build steps.

End-to-End Testing

End-to-End Testing — the containerized e2e (OAP + BanyanDB + .NET 8/10 demos) that verifies trace, log, and metric reporting.

Quick Reference

Topic	Default	Notes
Protocol version	`v8`	`Transport.ProtocolVersion`
Trace header	`sw8`	`HeaderVersions` (`sw8` only)
Reporter	`grpc`	`grpc` or `kafka` — see Transports
OAP gRPC server	`localhost:11800`	`Transport.gRPC.Servers`
Activation	env var	`ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyApm.Agent.AspNetCore`
Service name	required	`SkyWalking:ServiceName` (env `SKYWALKING__SERVICENAME`)
Config file	`skyapm.json`	also `skyapm.{Environment}.json`; see Configuration

The agent no-ops if SkyWalking:ServiceName is empty or SkyWalking:Enable is false.