Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/elastic/ecs-dotnet

.NET integrations that use the Elastic Common Schema (ECS)
https://github.com/elastic/ecs-dotnet
dotnet ecs elasticsearch
Last synced: about 1 month ago
JSON representation
.NET integrations that use the Elastic Common Schema (ECS)
Host: GitHub
URL: https://github.com/elastic/ecs-dotnet
Owner: elastic
License: apache-2.0
Created: 2019-07-03T00:00:01.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2024-05-29T15:11:21.000Z (6 months ago)
Last Synced: 2024-05-30T00:23:23.965Z (6 months ago)
Topics: dotnet, ecs, elasticsearch
Language: HTML
Homepage: https://www.elastic.co/guide/en/ecs-logging/dotnet/current/setup.html
Size: 3.67 MB
Stars: 97
Watchers: 25
Forks: 53
Open Issues: 18
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- License: license.txt
Awesome Lists containing this project

README

        

# Elastic Common Schema .NET

[![Build Status](https://apm-ci.elastic.co/buildStatus/icon?job=apm-agent-dotnet%2Fecs-dotnet-mbp%2Fmain)](https://apm-ci.elastic.co/job/apm-agent-dotnet/job/ecs-dotnet-mbp/job/main/)

This repository contains .NET integrations that use the Elastic Common Schema (ECS), including popular .NET logging frameworks. Read the [announcement post](https://www.elastic.co/blog/elastic-common-schema-dotnet-library-and-integrations-released-for-elasticsearch).

The Elastic Common Schema defines a common set of fields for ingesting data into Elasticsearch. A common schema helps you correlate data from sources like logs and metrics or IT operations analytics and security analytics. Further information on ECS can be found in the official [Elastic documentation](https://www.elastic.co/guide/en/ecs/current/index.html) or [github repository](https://github.com/elastic/ecs).

Contributions are welcome, please read our [guidelines](https://github.com/elastic/ecs-dotnet/tree/main/contributing.md).

---

### Versioning

Version components: `{major}.{minor}.{patch}`

These libraries are not versioned according to [SemVer](https://semver.org/) principles. Backwards compatibility is only guaranteed within *minor* versions, since ECS only makes this guarantee. Patch releases of this library will not seek to introduce breaking changes, but will be used to address bug fixes within that minor version.

Each assembly release indicates the ECS version that it is compatible with (see _releases_), but typically the minor version number of the assembly correlates to the compatible version of ECS; for example; all of `1.4.0`, `1.4.1`, `1.4.2` and `1.4.3` are compatible with ECS version `1.4.0`.

The assemblies are versioned using an assembly identity of `major.minor.*` as opposed to `major.*` as is common when following SemVer.

---

# Integrations

Official NuGet packages can be referenced from [NuGet.org](https://www.nuget.org).

| Package Name            | Purpose          | Download         |

| ----------------------- | ---------------- | -----------------|

| `Elastic.CommonSchema`  |  Foundational project that contains a full C# representation of ECS, used by the other integrations listed. | [![NuGet Release][ElasticCommonSchema-image]][ElasticCommonSchema-nuget-url]  |

| `Elastic.CommonSchema.Serilog`  |  Formats a Serilog log message into a JSON representation that can be indexed into Elasticsearch. | [![NuGet Release][ElasticCommonSchemaSerilog-image]][ElasticCommonSchemaSerilog-nuget-url]  |

| `Elastic.CommonSchema.NLog`  |  Formats an NLog message into a JSON representation that can be indexed into Elasticsearch. | [![NuGet Release][ElasticCommonSchemaNLog-image]][ElasticCommonSchemaNLog-nuget-url]  |

| `Elastic.CommonSchema.Log4net`  |  Formats a log4net message into a JSON representation that can be indexed into Elasticsearch. | [![NuGet Release][ElasticCommonSchemaLog4net-image]][ElasticCommonSchemaLog4net-nuget-url]  |

| `Elastic.Extensions.Logging`  | Microsoft Extension Logging provider that writes directly to ElasticSearch or ElasticCloud. | [![NuGet Release][ElasticIngestLogging-image]][ElasticIngestLogging-nuget-url]  |

| `Elastic.NLog.Targets`  | NLog target that writes directly to ElasticSearch or ElasticCloud. | [![NuGet Release][ElasticIngestNLog-image]][ElasticIngestNLog-nuget-url]  |

| `Elastic.Serilog.Sinks`  | Serilog sink that writes directly to ElasticSearch or ElasticCloud. | [![NuGet Release][ElasticIngestSerilog-image]][ElasticIngestSerilog-nuget-url]  |

| `Elastic.Apm.SerilogEnricher`   |  Adds transaction id and trace id to every Serilog log message that is created during a transaction. This works in conjunction with the Elastic.CommonSchema.Serilog package and forms a solution to distributed tracing with Serilog. | [![NuGet Release][ElasticApmSerilogEnricher-image]][ElasticApmSerilogEnricher-nuget-url]  |

| `Elastic.Apm.NLog`              |  Introduces two special placeholder variables (ElasticApmTraceId and ElasticApmTransactionId) for use within your NLog templates. | [![NuGet Release][ElasticApmNLog-image]][ElasticApmNLog-nuget-url]  |

| `Elastic.CommonSchema.BenchmarkDotNetExporter`  |  An exporter for BenchmarkDotnet that can index benchmarking results directly into Elasticsearch, which can be helpful for detecting code-related performance problems over time. | [![NuGet Release][ElasticBenchmarkDotNetExporter-image]][ElasticBenchmarkDotNetExporter-nuget-url]  |

[ElasticCommonSchema-nuget-url]:https://www.nuget.org/packages/Elastic.CommonSchema/

[ElasticCommonSchema-image]:https://img.shields.io/nuget/v/Elastic.CommonSchema.svg

[ElasticCommonSchemaSerilog-nuget-url]:https://www.nuget.org/packages/Elastic.CommonSchema.Serilog/

[ElasticCommonSchemaSerilog-image]:https://img.shields.io/nuget/v/Elastic.CommonSchema.Serilog.svg

[ElasticCommonSchemaNLog-nuget-url]:https://www.nuget.org/packages/Elastic.CommonSchema.NLog/

[ElasticCommonSchemaNLog-image]:https://img.shields.io/nuget/v/Elastic.CommonSchema.NLog.svg

[ElasticCommonSchemaLog4net-nuget-url]:https://www.nuget.org/packages/Elastic.CommonSchema.Log4net/

[ElasticCommonSchemaLog4net-image]:https://img.shields.io/nuget/v/Elastic.CommonSchema.Log4net.svg

[ElasticIngestLogging-nuget-url]:https://www.nuget.org/packages/Elastic.Extensions.Logging/

[ElasticIngestLogging-image]:https://img.shields.io/nuget/v/Elastic.Extensions.Logging.svg

[ElasticIngestNLog-nuget-url]:https://www.nuget.org/packages/Elastic.NLog.Targets/

[ElasticIngestNLog-image]:https://img.shields.io/nuget/v/Elastic.NLog.Targets.svg

[ElasticIngestSerilog-nuget-url]:https://www.nuget.org/packages/Elastic.Serilog.Sinks/

[ElasticIngestSerilog-image]:https://img.shields.io/nuget/v/Elastic.Serilog.Sinks.svg

[ElasticApmSerilogEnricher-nuget-url]:https://www.nuget.org/packages/Elastic.Apm.SerilogEnricher/

[ElasticApmSerilogEnricher-image]:https://img.shields.io/nuget/v/Elastic.Apm.SerilogEnricher.svg

[ElasticApmNLog-nuget-url]:https://www.nuget.org/packages/Elastic.Apm.NLog/

[ElasticApmNLog-image]:https://img.shields.io/nuget/v/Elastic.Apm.NLog.svg

[ElasticBenchmarkDotNetExporter-nuget-url]:https://www.nuget.org/packages/Elastic.CommonSchema.BenchmarkDotNetExporter/

[ElasticBenchmarkDotNetExporter-image]:https://img.shields.io/nuget/v/Elastic.CommonSchema.BenchmarkDotNetExporter.svg

## Foundation Library

### [Elastic.CommonSchema](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema)

Foundational project that contains a full C# representation of ECS. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema)

## Logging

### [Elastic.Extensions.Logging](src/Elastic.Extensions.Logging/ReadMe.md)

Elastic Stack (ELK) logger provider for `Microsoft.Extensions.Logging`.

Writes direct to Elasticsearch using the Elastic Common Schema, with semantic logging of structured data from message and scope values.

This logger provider can be added directly to Microsoft.Extensions.Logging:

```csharp

using Elastic.Extensions.Logging;

// ...

    .ConfigureLogging((hostContext, loggingBuilder) =>

    {

        loggingBuilder.AddElasticsearch();

    })

```

### [Elastic.CommonSchema.Serilog](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.Serilog)

Formats a Serilog event into a JSON representation that adheres to the Elastic Common Schema. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.Serilog)

```csharp

var logger = new LoggerConfiguration()

    .WriteTo.Console(new EcsTextFormatter())

    .CreateLogger();

```

Serilog Sink [Elastic.Serilog.Sinks](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.Serilog.Sinks) is also available, which writes directly to Elasticsearch using the Elastic Common Schema.

### [Elastic.CommonSchema.NLog](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.NLog)

Formats an NLog event into a JSON representation that adheres to the Elastic Common Schema. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.NLog)

```csharp

var config = new LoggingConfiguration();

var consoleTarget = new ConsoleTarget("console") { Layout = new EcsLayout() };  // Use the ECS layout.

config.AddRule(LogLevel.Debug, LogLevel.Fatal, consoleTarget);

LogManager.Configuration = config;

var logger = LogManager.GetCurrentClassLogger();

```

NLog Target [Elastic.NLog.Targets](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.NLog.Targets) is also available, which writes directly to Elasticsearch using the Elastic Common Schema.

### [Elastic.CommonSchema.Log4net](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.Log4net)

Formats a log4net event into a JSON representation that adheres to the Elastic Common Schema. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.Log4net)

```csharp

var hierarchy = (Hierarchy)LogManager.CreateRepository(Guid.NewGuid().ToString());

var appender = new ConsoleAppender { Layout = new EcsLayout() }; // Use the ECS layout.

hierarchy.Root.AddAppender(appender);

hierarchy.Root.Level = Level.All;

hierarchy.Configured = true;

```

## APM

### [Elastic.Apm.SerilogEnricher](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.Apm.SerilogEnricher)

Adds transaction id and trace id to every Serilog log message that is created during a transaction. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.Apm.SerilogEnricher)

```csharp

var logger = new LoggerConfiguration()

    .Enrich.WithElasticApmCorrelationInfo()

    .WriteTo.Console(outputTemplate: "[{ElasticApmTraceId} {ElasticApmTransactionId} {Message:lj} {NewLine}{Exception}")

    .CreateLogger();

```

When combined with `Elastic.CommonSchema.Serilog` the trace and transaction id will automatically appear in ECS as well.

```csharp

var logger = new LoggerConfiguration()

    .Enrich.WithElasticApmCorrelationInfo()

    .WriteTo.Console(new EcsTextFormatter()) // APM information persisted in ECS as well

    .CreateLogger();

```

### [Elastic.Apm.NLog](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.Apm.NLog)

Introduce two special place holder variables (`ElasticApmTraceId`, `ElasticApmTransactionId`) easily into your NLog templates.

[Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.Apm.NLog)

```csharp

// Logged message will be in format of `trace-id|transation-id|InTransaction`

// or `||InTransaction` if the place holders are not available

var consoleTarget = new ConsoleTarget("console");

consoleTarget.Layout = "${ElasticApmTraceId}|${ElasticApmTransactionId}|${message}";

config.AddRule(LogLevel.Debug, LogLevel.Fatal, consoleTarget);

LogManager.Configuration = config;

var logger = LogManager.GetCurrentClassLogger();

```

When using EcsLayout from `Elastic.CommonSchema.NLog` then trace and transaction id will automatically appear in ECS.

## Benchmarking

### [Elastic.CommonSchema.BenchmarkDotNetExporter](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.BenchmarkDotNetExporter)

An exporter for [BenchmarkDotnet](https://github.com/dotnet/BenchmarkDotNet) that can index benchmarking result output directly into Elasticsearch. [Learn more...](https://github.com/elastic/ecs-dotnet/tree/main/src/Elastic.CommonSchema.BenchmarkDotNetExporter)

```csharp

var options = new ElasticsearchBenchmarkExporterOptions(url)

{

	GitBranch = "externally-provided-branch",

	GitCommitMessage = "externally provided git commit message",

	GitRepositoryIdentifier = "repository"

};

var exporter = new ElasticsearchBenchmarkExporter(options);

var config = CreateDefaultConfig().With(exporter);

BenchmarkRunner.Run(typeof(Md5VsSha256), config);

```

# Examples

- [Elastic.CommonSchema.Serilog and ASP.NET Core](/examples/aspnetcore-with-serilog/)

## Copyright and License

This software is Copyright (c) 2014-2020 by Elasticsearch BV.

This is free software, licensed under: [The Apache License Version 2.0](https://github.com/elastic/ecs-dotnet/blob/main/license.txt).