Configuration Reference

This is the authoritative configuration reference for the SkyAPM .NET agent (SkyAPM-dotnet) — a C#/.NET auto-instrumentation agent for the .NET ecosystem that reports to an Apache SkyWalking backend. Every key lives under the top-level SkyWalking root and reports to the SkyWalking OAP backend.

Protocol note: SkyAPM-dotnet speaks the SkyWalking v8 wire protocol and the sw8 cross-process header only. The legacy sw6/v6 protocol is no longer supported. The defaults are Transport.ProtocolVersion = "v8" and HeaderVersions = ["sw8"]; do not change them.

The agent targets net8.0 and net10.0 (LTS), with foundational libraries also built for netstandard2.0. This reference applies to version 2.3.0.

How configuration is loaded

The agent builds its configuration from several sources. Listed from lowest to highest precedence (each source overrides the ones above it):

1. Built-in defaults — every key has a hard-coded default (the values in this document).
2. appsettings.json and appsettings.{Environment}.json.
3. skywalking.json and skywalking.{Environment}.json.
4. skyapm.json and skyapm.{Environment}.json — the canonical, dedicated agent config file (generate it with the CLI).
5. External config file referenced by the SKYAPM__CONFIG__PATH (or legacy SKYWALKING__CONFIG__PATH) environment variable.
6. Environment variables — using __ (double underscore) as the section separator, e.g. SKYWALKING__TRANSPORT__GRPC__SERVERS overrides SkyWalking:Transport:gRPC:Servers.
7. Host IConfiguration — the application’s own configuration, applied last.

In short: environment variables and the host configuration win over the JSON files, and skyapm.json wins over appsettings.json/skywalking.json. The {Environment} token follows the ASP.NET Core environment (Development / Staging / Production, etc.).

{Environment} is resolved from ASPNETCORE_ENVIRONMENT / DOTNET_ENVIRONMENT.

Activation

Enable zero-code instrumentation for ASP.NET Core by adding the agent to the hosting-startup assemblies — no code changes required:

export ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyApm.Agent.AspNetCore

Set the service name through SkyWalking:ServiceName (or the SKYWALKING__SERVICENAME environment variable). The agent no-ops if ServiceName is empty or SkyWalking:Enable is false. See Getting Started for an end-to-end walkthrough.

General

These keys sit directly under SkyWalking.

Sampling

Keys under SkyWalking:Sampling.

Wildcard usage: a/b/c matches a/b/c, a/* matches a/b, a/** matches a/b/c/d, and a/?/c matches a/b/c.

Logging (agent self-log)

Keys under SkyWalking:Logging. These control the agent’s own diagnostic log (a Serilog rolling file), not the application logs that are shipped to OAP (for that, see Diagnostics.Logging).

Transport

Keys under SkyWalking:Transport. Controls how telemetry is buffered, batched, and reported. See Transports for a deeper discussion of the gRPC and Kafka reporters.

Transport.gRPC

Keys under SkyWalking:Transport:gRPC. Used when Reporter = "grpc".

The agent reports to the OAP gRPC receiver on port 11800. Ports 12800 / 8080 are the OAP query / UI endpoints and are not used by the agent.

Transport.Kafka

Keys under SkyWalking:Transport:Kafka. Used when Reporter = "kafka".

Tracing

Keys under SkyWalking:Tracing.

Diagnostics.Logging

Keys under SkyWalking:Diagnostics:Logging. Controls which application logs (via Microsoft.Extensions.Logging) are shipped to OAP.

Component.AspNetCore

Keys under SkyWalking:Component:AspNetCore. Controls capture of inbound ASP.NET Core request data as span tags (implemented by the hosting diagnostic handler).

Component.HttpClient

Keys under SkyWalking:Component:HttpClient. Controls tracing and data capture for outbound HttpClient calls (implemented by the request diagnostic handler).

Example skyapm.json

A complete, correct example using sw8 / v8 and realistic defaults. The fastest way to produce this file is the CLI generator; the structure below matches its output.

{
  "SkyWalking": {
    "Enable": true,
    "ServiceName": "My_Service",
    "Namespace": "",
    "HeaderVersions": [
      "sw8"
    ],
    "Sampling": {
      "SamplePer3Secs": -1,
      "Percentage": -1,
      "IgnorePaths": [
        "/health",
        "/metrics"
      ],
      "LogSqlParameterValue": false
    },
    "Logging": {
      "Level": "Information",
      "FilePath": "logs/skyapm-{Date}.log",
      "FileSizeLimitBytes": 268435456,
      "FlushToDiskInterval": 1000,
      "RollingInterval": "Day",
      "RollOnFileSizeLimit": false,
      "RetainedFileCountLimit": 10,
      "RetainedFileTimeLimit": 864000000
    },
    "Transport": {
      "Reporter": "grpc",
      "ProtocolVersion": "v8",
      "QueueSize": 10000,
      "BatchSize": 2000,
      "Parallel": 5,
      "Interval": 50,
      "gRPC": {
        "Servers": "localhost:11800",
        "ConnectTimeout": 10000,
        "Timeout": 10000,
        "ReportTimeout": 600000,
        "Authentication": ""
      },
      "Kafka": {
        "BootstrapServers": "localhost:9092",
        "TopicTimeoutMs": 3000,
        "MessageTimeoutMs": 5000,
        "TopicMeters": "skywalking-meters",
        "TopicCLRMetrics": "skywalking-clr-metrics",
        "TopicSegments": "skywalking-segments",
        "TopicProfilings": "skywalking-profilings",
        "TopicManagements": "skywalking-managements",
        "TopicLogs": "skywalking-logs"
      }
    },
    "Tracing": {
      "ExceptionMaxDepth": 3,
      "DbPeerSimpleFormat": false
    },
    "Diagnostics": {
      "Logging": {
        "CollectLevel": "Information"
      }
    },
    "Component": {
      "AspNetCore": {
        "CollectCookies": null,
        "CollectHeaders": null,
        "CollectBodyContentTypes": null,
        "CollectBodyLengthThreshold": 2048
      },
      "HttpClient": {
        "IgnorePaths": null,
        "StopHeaderPropagationPaths": null,
        "CollectRequestHeaders": null,
        "CollectRequestBodyContentTypes": null,
        "CollectResponseBodyContentTypes": null,
        "CollectBodyLengthThreshold": 2048
      }
    }
  }
}

See also

• CLI generator — generate skyapm.json from the command line.
• Transports — gRPC vs. Kafka reporter details.
• Getting Started — install and activate the agent.
• Documentation index