Managed Service for OpenTelemetry:Report .NET application data through SkyWalking

Prerequisites

Before you begin, make sure that you have:

• An Alibaba Cloud account with Managed Service for OpenTelemetry activated

• A .NET Core project

• The .NET SDK installed locally

Background information

SkyWalking is a popular application performance monitoring (APM) service developed in China. It is designed for microservices, cloud-native architectures, and container-based architectures such as Docker, Kubernetes, and Mesos. SkyWalking is also a distributed tracing system.

Step 1: Get the SkyWalking endpoint and token

1. Log on to the Managed Service for OpenTelemetry console.

2. In the left-side navigation pane, click Cluster Configurations. Then, click the Access point information tab.

3. In the top navigation bar, select a region. In the Cluster Information section, turn on Show Token.

4. In the Client section, click SkyWalking.

5. In the Related Information column, copy the endpoint and token values for use in later steps.

   

Step 2: Install the SkyWalking agent

Navigate to your .NET project root and install the agent NuGet package:

dotnet add package SkyAPM.Agent.AspNetCore

Set the required environment variables:

Linux or macOS

export ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyAPM.Agent.AspNetCore
export SKYWALKING__SERVICENAME=<your-service-name>

Windows (Command Prompt)

set ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyAPM.Agent.AspNetCore
set SKYWALKING__SERVICENAME=<your-service-name>

Windows (PowerShell)

$env:ASPNETCORE_HOSTINGSTARTUPASSEMBLIES="SkyAPM.Agent.AspNetCore"
$env:SKYWALKING__SERVICENAME="<your-service-name>"

Replace <your-service-name> with a name that identifies your application, such as my-order-service.

Step 3: Configure the agent

Create a skyapm.json configuration file in your project root. Choose one of the following methods.

dotnet tool install -g SkyAPM.DotNet.CLI

# Add the tool to your PATH if it is not already available.
# Replace /path/to with the actual path to your .dotnet/tools directory.
export PATH="$PATH:/path/to/.dotnet/tools/"

dotnet skyapm config <your-service-name> <your-endpoint>

{
  "SkyWalking": {
    "ServiceName": "<your-service-name>",
    "Namespace": "",
    "HeaderVersions": [
      "sw8"
    ],
    "Sampling": {
      "SamplePer3Secs": -1,
      "Percentage": -1.0,
      "LogSqlParameterValue": false
    },
    "Logging": {
      "Level": "Information",
      "FilePath": "logs/skyapm-{Date}.log"
    },
    "Transport": {
      "Interval": 3000,
      "ProtocolVersion": "v8",
      "QueueSize": 30000,
      "BatchSize": 3000,
      "gRPC": {
        "Servers": "<your-endpoint>",
        "Authentication": "<your-token>",
        "Timeout": 100000,
        "ConnectTimeout": 100000,
        "ReportTimeout": 600000
      }
    }
  }
}

Step 4: Verify the integration

1. Start your application:

   dotnet run

2. Send a few requests to your application to generate trace data. For example:

   curl http://localhost:5000/

   Send several requests so the agent has data to report.

3. Check the agent log file at logs/skyapm-<date>.log in your project directory. A successful connection produces log entries similar to the following:

   

4. Log on to the Managed Service for OpenTelemetry console and confirm that your application name appears under your traces.

If the log file shows connection errors, verify the following:

• The endpoint and token values in skyapm.json match the values from the console.

• Your network allows outbound connections to the endpoint. For VPC endpoints, your application must run within the same VPC.

Build from source

To build the SkyWalking .NET agent from source:

# Clone the repository
git clone https://github.com/SkyAPM/SkyAPM-dotnet.git

cd SkyAPM-dotnet/

# Check out the desired release tag
git checkout <tag-name>

# Initialize submodules
git submodule init
git submodule update

# Restore dependencies and build
dotnet restore
dotnet build src/SkyApm.Transport.Grpc.Protocol
dotnet build skyapm-dotnet.sln

Sample code

For a complete working example, see the skywalking-demo repository on GitHub.

FAQ

dotnet skyapm config fails to generate skyapm.json

Try one of the following solutions:

• Create the file manually (recommended). The CLI tool only generates a template skyapm.json file. Follow Option B: Create the file manually to create and configure the file yourself.

• Switch to .NET 6.0. The SkyAPM.DotNet.CLI tool may not be compatible with your current .NET SDK version. Install .NET 6.0 and retry.