https://github.com/engineering87/opensharptrace
.NET library to automate trace and observability of REST APIs in microservices environment
https://github.com/engineering87/opensharptrace
dotnet microservices observability rest-api restful trace webapi
Last synced: 7 months ago
JSON representation
.NET library to automate trace and observability of REST APIs in microservices environment
- Host: GitHub
- URL: https://github.com/engineering87/opensharptrace
- Owner: engineering87
- License: mit
- Created: 2022-09-06T23:08:45.000Z (over 3 years ago)
- Default Branch: develop
- Last Pushed: 2025-04-11T07:37:53.000Z (12 months ago)
- Last Synced: 2025-04-11T09:45:11.090Z (12 months ago)
- Topics: dotnet, microservices, observability, rest-api, restful, trace, webapi
- Language: C#
- Homepage:
- Size: 85 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenSharpTrace
[](https://opensource.org/licenses/MIT)
[](https://www.nuget.org/packages/OpenSharpTrace)
[](https://github.com/engineering87/OpenSharpTrace/issues)
[](https://github.com/engineering87/OpenSharpTrace/actions/workflows/dotnet.yml)
[](https://github.com/engineering87/OpenSharpTrace)
OpenSharpTrace is a C# .NET library that allows extending any WebApi controller to automate a custom trace and observability of REST APIs in microservices environment.
## Features
OpenSharpTrace offers the following features to enhance tracing and logging capabilities in .NET applications:
- **Distributed Tracing**: Seamlessly integrate distributed tracing into your application to monitor and analyze requests across services.
- **Customizable Sampling**: Support for configurable sampling strategies to manage trace data volume effectively.
- **Extensible Framework**: Easily extend and adapt the library to fit your specific tracing needs.
- **Performance Optimization**: Minimal performance overhead to ensure smooth application operation.
- **Multi-environment Support**: Effortless configuration and deployment across various environments, including development, staging, and production.
These features make OpenSharpTrace a powerful and flexible choice for implementing robust tracing solutions in your .NET ecosystem.
## Installation
You can install the library via the NuGet package manager with the following command:
```bash
dotnet add package OpenSharpTrace
```
### How it works
OpenSharpTrace implements a custom controller that overrides the `OnActionExecuting` and `OnActionExecuted` events to capture the request and response data. These are then encapsulated in a Trace object, which can be persisted specifically to SQL. All the relevant information needed for tracing both the request and response is automatically persisted, in details:
* **TransactionId**: identifier associated with the request (retrieved from the header).
* **ServerId**: name of the server.
* **ClientId**: name of the client (retrieved from the header).
* **HttpMethod**: HTTP method on the controller.
* **HttpPath**: HTTP endpoint on the controller.
* **HttpStatusCode**: HTTP result status code.
* **ActionDescriptor**: full action descriptor detail.
* **RemoteAddress**: IP address of the consumer.
* **JsonRequest**: JSON serialization of the request.
* **JsonResponse**: JSON serialization of the response.
* **TimeStamp**: UTC timestamp.
* **Exception**: possible exception message.
* **ExecutionTime**: total action execution time in milliseconds.
**TransactionId** and **ConsumerId** retrieved from the header should be enhanced by the client to allow a possible correlations between calls.
In order to enhance the two parameters, client will have to add the followuing header keys:
* `TRANSACTION` for TransactionId
* `CONSUMER` for ClientId
for example:
```csharp
HttpRequestMessage request = new HttpRequestMessage();
request.RequestUri = new Uri("API_URI");
request.Headers.Add("TRANSACTION", "123456789");
request.Headers.Add("CONSUMER", "client-name");
```
### How to use it
To use the OpenSharpTrace library, each WebApi controller must extend the **OpenSharpTraceController** controller:
```csharp
using OpenSharpTrace.Abstractions.Persistence;
using OpenSharpTrace.Controllers;
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : OpenSharpTraceController
```
each controller must implement the following constructor, for example:
```csharp
public WeatherForecastController(
ILogger logger,
ITraceQueue transactionQueue) : base(logger, transactionQueue)
{
_logger = logger;
}
```
for older version of the library (2.0.0 or above):
```csharp
public WeatherForecastController(
ILoggerFactory loggerFactory,
ISqlTraceRepository repository)
: base(loggerFactory, repository)
{
_logger = loggerFactory.CreateLogger(GetType().ToString());
}
```
You also need to register the OpenSharpTrace middleware.
To do this, add the following configurations under WebApplicationBuilder:
```csharp
using OpenSharpTrace.Middleware;
services.RegisterOpenSharpTrace();
// ...
```
In the source code you can find a simple test Web Api.
### Available connectors
#### SQL
Currently the only connector available is the SQL connector on the *Trace* table using *Entity Framework Core*.
The following is the table creation script:
```tsql
CREATE TABLE [dbo].[Trace](
[Id] [bigint] IDENTITY(1,1) NOT NULL,
[TransactionId] [nvarchar](MAX) NULL,
[ServerId] [nvarchar](MAX) NULL,
[ClientId] [nvarchar](MAX) NULL,
[HttpMethod] [nvarchar](7) NULL,
[HttpPath] [nvarchar](MAX) NULL,
[HttpStatusCode] [int] NULL,
[ActionDescriptor] [nvarchar](MAX) NULL,
[RemoteAddress] [nvarchar](MAX) NULL,
[JsonRequest] [nvarchar](MAX) NULL,
[JsonResponse] [nvarchar](MAX) NULL,
[TimeStamp] [datetime2](7) NULL,
[Exception] [nvarchar](MAX) NULL,
[ExecutionTime] [numeric] NULL,
) ON [PRIMARY]
```
From version 4.1.0 onwards, table creation is handled automatically, in case it is missing on the SQL instance.
Remember to populate the **TraceDb** key within the SQL connection strings config file:
```xml
"ConnectionStrings": {
"TraceDb": "Server=(***;Database=***;Trusted_Connection=True;MultipleActiveResultSets=true"
},
```
## Contributing
Thank you for considering to help out with the source code!
If you'd like to contribute, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base.
* [Setting up Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git)
* [Fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
* [Open an issue](https://github.com/engineering87/OpenSharpTrace/issues) if you encounter a bug or have a suggestion for improvements/features
### Licensee
OpenSharpTrace source code is available under MIT License, see license in the source.
### Contact
Please contact at francesco.delre[at]protonmail.com for any details.