{"id":21670508,"url":"https://github.com/engineering87/opensharptrace","last_synced_at":"2025-09-01T16:38:43.238Z","repository":{"id":65338679,"uuid":"533529540","full_name":"engineering87/OpenSharpTrace","owner":"engineering87","description":".NET library to automate trace and observability of REST APIs in microservices environment","archived":false,"fork":false,"pushed_at":"2025-04-11T07:37:53.000Z","size":87,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-11T09:45:11.090Z","etag":null,"topics":["dotnet","microservices","observability","rest-api","restful","trace","webapi"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/engineering87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-06T23:08:45.000Z","updated_at":"2025-04-11T07:37:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"c56f011e-9200-4d50-9a96-5ef4d6b50a08","html_url":"https://github.com/engineering87/OpenSharpTrace","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engineering87%2FOpenSharpTrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engineering87%2FOpenSharpTrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engineering87%2FOpenSharpTrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engineering87%2FOpenSharpTrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/engineering87","download_url":"https://codeload.github.com/engineering87/OpenSharpTrace/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248507468,"owners_count":21115607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotnet","microservices","observability","rest-api","restful","trace","webapi"],"created_at":"2024-11-25T12:32:43.936Z","updated_at":"2025-04-12T02:41:20.594Z","avatar_url":"https://github.com/engineering87.png","language":"C#","readme":"# OpenSharpTrace\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Nuget](https://img.shields.io/nuget/v/OpenSharpTrace?style=plastic)](https://www.nuget.org/packages/OpenSharpTrace)\n![NuGet Downloads](https://img.shields.io/nuget/dt/OpenSharpTrace)\n[![issues - opensharptrace](https://img.shields.io/github/issues/engineering87/OpenSharpTrace)](https://github.com/engineering87/OpenSharpTrace/issues)\n[![Build](https://github.com/engineering87/OpenSharpTrace/actions/workflows/dotnet.yml/badge.svg)](https://github.com/engineering87/OpenSharpTrace/actions/workflows/dotnet.yml)\n[![stars - opensharptrace](https://img.shields.io/github/stars/engineering87/OpenSharpTrace?style=social)](https://github.com/engineering87/OpenSharpTrace)\n\nOpenSharpTrace is a C# .NET library that allows extending any WebApi controller to automate a custom trace and observability of REST APIs in microservices environment.\n\n## Features\nOpenSharpTrace offers the following features to enhance tracing and logging capabilities in .NET applications:\n\n- **Distributed Tracing**: Seamlessly integrate distributed tracing into your application to monitor and analyze requests across services.\n- **Customizable Sampling**: Support for configurable sampling strategies to manage trace data volume effectively.\n- **Extensible Framework**: Easily extend and adapt the library to fit your specific tracing needs.\n- **Performance Optimization**: Minimal performance overhead to ensure smooth application operation.\n- **Multi-environment Support**: Effortless configuration and deployment across various environments, including development, staging, and production.\n\nThese features make OpenSharpTrace a powerful and flexible choice for implementing robust tracing solutions in your .NET ecosystem.\n\n## Installation\nYou can install the library via the NuGet package manager with the following command:\n\n```bash\ndotnet add package OpenSharpTrace\n```\n\n### How it works\nOpenSharpTrace 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:\n\n* **TransactionId**: identifier associated with the request (retrieved from the header).\n* **ServerId**: name of the server.\n* **ClientId**: name of the client (retrieved from the header).\n* **HttpMethod**: HTTP method on the controller.\n* **HttpPath**: HTTP endpoint on the controller.\n* **HttpStatusCode**: HTTP result status code.\n* **ActionDescriptor**: full action descriptor detail.\n* **RemoteAddress**: IP address of the consumer.\n* **JsonRequest**: JSON serialization of the request.\n* **JsonResponse**: JSON serialization of the response.\n* **TimeStamp**: UTC timestamp.\n* **Exception**: possible exception message.\n* **ExecutionTime**: total action execution time in milliseconds.\n\n**TransactionId** and **ConsumerId** retrieved from the header should be enhanced by the client to allow a possible correlations between calls.\nIn order to enhance the two parameters, client will have to add the followuing header keys:\n\n* `TRANSACTION` for TransactionId\n* `CONSUMER` for ClientId\n\nfor example:\n\n```csharp\nHttpRequestMessage request = new HttpRequestMessage();\nrequest.RequestUri = new Uri(\"API_URI\");\nrequest.Headers.Add(\"TRANSACTION\", \"123456789\");\nrequest.Headers.Add(\"CONSUMER\", \"client-name\");\n```\n\n### How to use it\n\nTo use the OpenSharpTrace library, each WebApi controller must extend the **OpenSharpTraceController** controller:\n\n```csharp\nusing OpenSharpTrace.Abstractions.Persistence;\nusing OpenSharpTrace.Controllers;\n\n[ApiController]\n[Route(\"api/[controller]\")]\npublic class WeatherForecastController : OpenSharpTraceController\n```\n\neach controller must implement the following constructor, for example:\n\n```csharp\npublic WeatherForecastController(\n\tILogger\u003cWeatherForecastController\u003e logger,\n\tITraceQueue\u003cTrace\u003e transactionQueue) : base(logger, transactionQueue)\n{\n\t_logger = logger;\n}\n```\n\nfor older version of the library (2.0.0 or above):\n\n```csharp\npublic WeatherForecastController(\n\tILoggerFactory loggerFactory, \n\tISqlTraceRepository repository) \n: base(loggerFactory, repository)\n{\n    _logger = loggerFactory.CreateLogger(GetType().ToString());\n}\n```\n\nYou also need to register the OpenSharpTrace middleware.\nTo do this, add the following configurations under WebApplicationBuilder:\n\n```csharp\nusing OpenSharpTrace.Middleware;\n\nservices.RegisterOpenSharpTrace();\n// ...\n```\n\nIn the source code you can find a simple test Web Api.\n\n### Available connectors\n\n#### SQL\n\nCurrently the only connector available is the SQL connector on the *Trace* table using *Entity Framework Core*.\nThe following is the table creation script:\n\n```tsql\nCREATE TABLE [dbo].[Trace](\n\t[Id] [bigint] IDENTITY(1,1) NOT NULL,\n\t[TransactionId] [nvarchar](MAX) NULL,\n\t[ServerId] [nvarchar](MAX) NULL,\n\t[ClientId] [nvarchar](MAX) NULL,\n\t[HttpMethod] [nvarchar](7) NULL,\n\t[HttpPath] [nvarchar](MAX) NULL,\n\t[HttpStatusCode] [int] NULL,\n\t[ActionDescriptor] [nvarchar](MAX) NULL,\n\t[RemoteAddress] [nvarchar](MAX) NULL,\n\t[JsonRequest] [nvarchar](MAX) NULL,\n\t[JsonResponse] [nvarchar](MAX) NULL,\n\t[TimeStamp] [datetime2](7) NULL,\n\t[Exception] [nvarchar](MAX) NULL,\n\t[ExecutionTime] [numeric] NULL,\n) ON [PRIMARY]\n```\nFrom version 4.1.0 onwards, table creation is handled automatically, in case it is missing on the SQL instance.\n\nRemember to populate the **TraceDb** key within the SQL connection strings config file:\n\n```xml\n  \"ConnectionStrings\": {\n    \"TraceDb\": \"Server=(***;Database=***;Trusted_Connection=True;MultipleActiveResultSets=true\"\n  },\n```\n\n## Contributing\nThank you for considering to help out with the source code!\nIf 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.\n\n * [Setting up Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git)\n * [Fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)\n * [Open an issue](https://github.com/engineering87/OpenSharpTrace/issues) if you encounter a bug or have a suggestion for improvements/features\n\n### Licensee\nOpenSharpTrace source code is available under MIT License, see license in the source.\n\n### Contact\nPlease contact at francesco.delre[at]protonmail.com for any details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengineering87%2Fopensharptrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fengineering87%2Fopensharptrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengineering87%2Fopensharptrace/lists"}