diff --git a/README.md b/README.md index 41192fca..08e731dd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ SkyAPM C#/.NET instrument agent ========== -Sky Walking logo +SkyAPM logo **SkyAPM-dotnet** is a community, open-source C#/.NET auto-instrumentation agent for the .NET ecosystem. It provides distributed tracing, application topology, and metrics for ASP.NET Core and .NET applications, and reports the collected telemetry to an [Apache SkyWalking](https://skywalking.apache.org/) backend over the `sw8` / `v8` protocol. It is an independent project and is not affiliated with or endorsed by the Apache Software Foundation. @@ -10,112 +10,48 @@ SkyAPM C#/.NET instrument agent [![releases](https://img.shields.io/github/release/skyapm/skyapm-dotnet.svg?style=flat-square)](https://github.com/SkyAPM/SkyAPM-dotnet/releases) [![Twitter Follow](https://img.shields.io/twitter/follow/asfskywalking.svg?style=flat-square&label=Follow&logo=twitter)](https://twitter.com/AsfSkyWalking) +## πŸ“– Documentation + +**Full documentation lives at [skyapm.github.io/SkyAPM-dotnet](https://skyapm.github.io/SkyAPM-dotnet/)** β€” getting started, installation & activation, the complete configuration reference (EN / δΈ­ζ–‡), transports (gRPC / Kafka), the supported-component list, plugins, logging, the CLI, and troubleshooting. + ## CI Build Status [![NET CI AND IT](https://github.com/SkyAPM/SkyAPM-dotnet/actions/workflows/net-ci-it.yml/badge.svg)](https://github.com/SkyAPM/SkyAPM-dotnet/actions/workflows/net-ci-it.yml) -## Nuget Packages +## NuGet Packages | Package Name | NuGet | Downloads | |--------------| ------- | ---- | | SkyAPM.Agent.AspNetCore | [![nuget](https://img.shields.io/nuget/v/SkyAPM.Agent.AspNetCore.svg?style=flat-square)](https://www.nuget.org/packages/SkyAPM.Agent.AspNetCore) | [![stats](https://img.shields.io/nuget/dt/SkyAPM.Agent.AspNetCore.svg?style=flat-square)](https://www.nuget.org/stats/packages/SkyAPM.Agent.AspNetCore?groupby=Version) | | SkyAPM.Agent.GeneralHost | [![nuget](https://img.shields.io/nuget/v/SkyAPM.Agent.GeneralHost.svg?style=flat-square)](https://www.nuget.org/packages/SkyAPM.Agent.GeneralHost) | [![stats](https://img.shields.io/nuget/dt/SkyAPM.Agent.GeneralHost.svg?style=flat-square)](https://www.nuget.org/stats/packages/SkyAPM.Agent.GeneralHost?groupby=Version) | -# Supported -- This project currently supports apps targeting net8.0 and net10.0 (the active .NET LTS releases). Apps on newer runtimes (e.g. net9.0) are covered via the net8.0 assemblies. -- [Supported middlewares, frameworks and libraries.](docs/Supported-list.md) - -# Features -A quick list of the SkyAPM .NET agent's capabilities: -- Application Topology -- Distributed Tracing over the SkyWalking sw8 (v8) protocol -- ASP.NET Core and ASP.NET diagnostics -- HttpClient and gRPC client/server diagnostics -- EntityFrameworkCore diagnostics (SqlServer, Sqlite, PostgreSQL/Npgsql, Pomelo MySQL) -- SqlClient and MySqlConnector peer formatters -- MongoDB, SmartSql, FreeSql, FreeRedis, MassTransit and CAP diagnostics -- Microsoft.Extensions.Logging (MSLogging) integration - -For the full plugin set, see [Supported middlewares, frameworks and libraries](docs/Supported-list.md). Browse all guides from the [docs index](docs/README.md). - -# Getting Started - -## Deploy SkyWalking Backend And UI - -#### Requirements -Start with v1.0.0, SkyAPM .NET Core Agent only supports SkyWalking 8.0 or higher. The SkyWalking doc is [here](https://skywalking.apache.org/docs/). - -## Install SkyWalking .NET Core Agent - -You can run the following command to install the SkyWalking .NET Core Agent in your project. - -``` -dotnet add package SkyAPM.Agent.AspNetCore -``` - -## How to use -Set the `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES` environment variable to support the activation of the SkyAPM .NET Core Agent. - -- Add the assembly name of `SkyAPM.Agent.AspNetCore` to the `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES` environment variable. - -### Examples -- On windows - -``` -dotnet new mvc -n sampleapp -cd sampleapp -dotnet add package SkyAPM.Agent.AspNetCore -set ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyAPM.Agent.AspNetCore -set SKYWALKING__SERVICENAME=sample_app -dotnet run -``` +## Quick start -- On macOS/Linux +Supported runtimes: **net8.0** and **net10.0**. -``` -dotnet new mvc -n sampleapp -cd sampleapp -dotnet add package SkyAPM.Agent.AspNetCore -export ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyAPM.Agent.AspNetCore -export SKYWALKING__SERVICENAME=sample_app +```bash +dotnet add package SkyApm.Agent.AspNetCore +export ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=SkyApm.Agent.AspNetCore +export SKYWALKING__SERVICENAME=my_service dotnet run ``` -## Configuration - -Install `SkyAPM.DotNet.CLI` - -``` -dotnet tool install -g SkyAPM.DotNet.CLI -``` - -For 2.2.x or older, use `dotnet skyapm config [your_service_name] [your_servers]` to generate config file. - -``` -dotnet skyapm config sample_app 192.168.0.1:11800 -``` - -For 2.3.x or newer, use `dotnet skyapm config ${your_service_name} [--reporter=grpc|kafka] [--grpcservers=...] [--kafkaservers=...]` to generate config file. +See [**Getting Started**](https://skyapm.github.io/SkyAPM-dotnet/docs/guides/getting-started/) for the full walkthrough, and the [**Configuration reference**](https://skyapm.github.io/SkyAPM-dotnet/docs/guides/skyapm_config/) for every option. -``` -# grpc -dotnet skyapm config sample_app --reporter=grpc --grpcservers=192.168.0.1:11800 +## Contributing -# kafka -dotnet skyapm config sample_app --reporter=kafka --kafkaservers=192.168.0.1:9092 -``` +See [Contributing to SkyAPM-dotnet](./CONTRIBUTING.md). -# Contributing -This section is in progress here: [Contributing to SkyAPM-dotnet](./CONTRIBUTING.md) +## Contact Us -# Contact Us -* Submit an issue +* Submit an issue on this repository for questions about the **.NET agent**. -If you have issues about SkyWalking protocol, its official backend, ask questions at their Apache official channels. All following channels are not suitable for .net agent, but good if you are facing backend/UI issues. +For questions about the **SkyWalking protocol or its backend/UI**, use the official Apache SkyWalking channels (these are not suitable for the .NET agent): * Submit an official Apache SkyWalking [issue](https://github.com/apache/skywalking/issues). * Mail list: **dev@skywalking.apache.org**. Mail to `dev-subscribe@skywalking.apache.org`, follow the reply to subscribe the mail list. -* Join `skywalking` channel at [Apache Slack](https://join.slack.com/t/the-asf/shared_invite/enQtNzc2ODE3MjI1MDk1LTAyZGJmNTg1NWZhNmVmOWZjMjA2MGUyOGY4MjE5ZGUwOTQxY2Q3MDBmNTM5YTllNGU4M2QyMzQ4M2U4ZjQ5YmY). If the link is not working, find the latest one at [Apache INFRA WIKI](https://cwiki.apache.org/confluence/display/INFRA/Slack+Guest+Invites). +* Join the `skywalking` channel at [Apache Slack](https://join.slack.com/t/the-asf/shared_invite/enQtNzc2ODE3MjI1MDk1LTAyZGJmNTg1NWZhNmVmOWZjMjA2MGUyOGY4MjE5ZGUwOTQxY2Q3MDBmNTM5YTllNGU4M2QyMzQ4M2U4ZjQ5YmY). If the link is not working, find the latest one at the [Apache INFRA WIKI](https://cwiki.apache.org/confluence/display/INFRA/Slack+Guest+Invites). * QQ Group: 392443393(2000/2000, not available), 901167865(available) -# License +## License + [Apache 2.0 License.](/LICENSE)