Elastic.Extensions.Logging 8.11.1

Elasticsearch 日志记录器提供者

Elasticsearch-Logstash-Kibana (ELK) 堆栈日志记录器提供者针对 Microsoft.Extensions.Logging。

使用 Elastic Common Schema (ECS) 直接写入 Elasticsearch，对来自消息和范围值的结构化数据进行语义日志记录。可以在 Kibana 控制台中查看和查询结果。

日志记录器使用 Elasticsearch.Net 低级客户端 来管理到 Elasticsearch 的网络连接。

使用方法

添加对 Elastic.Extensions.Logging 包的引用

dotnet add package Elastic.Extensions.Logging

然后，在主机构造期间使用提供的扩展方法将提供者添加到日志Builder中。

using Elastic.Extensions.Logging;

// ...

    .ConfigureLogging((hostContext, loggingBuilder) =>
    {
        loggingBuilder.AddElasticsearch();
    })

默认配置会将日志写入在 https://127.0.0.1:9200/ 运行的本地 Elasticsearch。

发送一些日志事件后，打开 Kibana（例如 https://127.0.0.1:5601/），为 "dotnet-*" 定义一个包含时间过滤器 "@timestamp" 的索引模式。

然后可以查看索引的日志事件。一些有用的列包括 log.level、log.logger、event.code、message、tags 和 process.thread.id。

如果您正在运行多个应用程序或多个服务器，您可能希望包括 service.type、service.version 和 host.hostname。

以下定义了其他字段，所有单个消息和作用域值都记录为 labels.* 自定义键/值对，例如 labels.CustomerId。

基本配置

对于部署，您通常希望用您实际的服务器位置覆盖配置。其他有用的配置值是环境标签，例如 开发/测试/生产。

{
  "Logging": {
    "Elasticsearch": {
      "NodeUris": [ "https://elastic-staging.example.com:9200" ],
      "Tags": [ "Staging" ]
    }
  }
}

注意：仅使用本地 Elasticsearch 实例时，无需任何配置，默认为 https://127.0.0.1:9200/。

示例程序

• 参见 带有 Extensions.Logging 的控制台

配置设置

日志提供程序将自动配置带有别名 Elasticsearch 下的任何日志设置。

以下使用默认设置：

{
  "Logging": {
    "Elasticsearch": {
      "IncludeHost": true,
      "IncludeProcess": true,
      "IncludeScopes": true,
      "IncludeUser": true,
      "Index": "dotnet-{0:yyyy.MM.dd}",
      "IndexOffset": null,
      "IsEnabled": true,
      "ListSeparator": ", ",
      "MapCorrelationValues": true,
      "Tags": [],
      "ShipTo": {
        "NodePoolType": "SingleNode",
        "NodeUris": [ "https://127.0.0.1:9200" ]
      }
    }
  }
}

根据连接池类型，ShipTo 设置可以具有以下属性：

如果您想从不同的部分进行配置，可以手动配置

    .ConfigureLogging((hostContext, loggingBuilder) =>
    {
        loggingBuilder.AddElasticsearch(options =>
            hostContext.Configuration.Bind("Logging:CustomElasticsearch", options));
    })

当然，也可以在代码中进行配置，例如将环境作为标签添加。

Elastic Cloud 配置

如果提供了 CloudId，则 ConnectionPoolType 默认为 Cloud

{
  "Logging": {
    "Elasticsearch": {
      "ShipTo": {
        "CloudId": "12345",
        "ApiKey": "abcdef"
      }
    }
  }
}

输出 - Elastic Common Schema (ECS)

发送到 Elasticsearch 的日志消息遵循 Elastic Common Schema (ECS)。

示例文档

_source 字段是从 LoggerProvider 发送的消息，包括 _index 和 _id（一个 GUID）。

{
  "_index": "dotnet-2020.04.12",
  "_type": "_doc",
  "_id": "563503a8-9d10-46ff-a09f-c6ccbf124db9",
  "_version": 1,
  "_score": null,
  "_source": {
    "MessageTemplate": "Unexpected error processing customer {CustomerId}.",
    "Scopes": [
      "IP address 2001:db8:85a3::8a2e:370:7334",
      "PlainScope"
    ],
    "agent": {
      "version": "1.0.0+bd3ad6",
      "type": "Elastic.Extensions.Logging.LoggerProvider"
    },
    "ecs": {
      "version": "1.5.0"
    },
    "error": {
      "message": "Calculation error",
      "type": "System.Exception",
      "stack_trace": "System.Exception: Calculation error\n ---> System.DivideByZeroException: Attempted to divide by zero.\n   at HelloElasticsearch.Worker.ExecuteAsync(CancellationToken stoppingToken) in /home/sly/Code/essential-logging/examples/HelloElasticsearch/Worker.cs:line 80\n   --- End of inner exception stack trace ---\n   at HelloElasticsearch.Worker.ExecuteAsync(CancellationToken stoppingToken) in /home/sly/Code/essential-logging/examples/HelloElasticsearch/Worker.cs:line 84"
    },
    "event": {
      "code": "5000",
      "action": "ErrorProcessingCustomer",
      "severity": 3
    },
    "host": {
      "os": {
        "platform": "Unix",
        "full": "Linux 4.15.0-91-generic #92-Ubuntu SMP Fri Feb 28 11:09:48 UTC 2020",
        "version": "4.15.0.91"
      },
      "hostname": "VUB1804",
      "architecture": "X64"
    },
    "log": {
      "level": "Error",
      "logger": "HelloElasticsearch.Worker"
    },
    "process": {
      "thread": {
        "id": 10
      },
      "pid": 25982,
      "name": "HelloElasticsearch"
    },
    "service": {
      "type": "HelloElasticsearch",
      "version": "1.0.0"
    },
    "user": {
      "id": "[email protected]",
      "name": "sly",
      "domain": "VUB1804"
    },
    "@timestamp": "2020-04-13T21:25:22.3352989+10:00",
    "tags": [
      "Development"
    ],
    "labels": {
      "ip": "2001:db8:85a3::8a2e:370:7334",
      "CustomerId": "12345"
    },
    "message": "Unexpected error processing customer 12345.",
    "trace": {
      "id": "c20bde1071f7cf4e9a6f368c824e05f7"
    },
    "transaction": {
      "id": "92ba5ee64d963746"
    }
  },
  "fields": {
    "@timestamp": [
      "2020-04-13T11:25:22.335Z"
    ]
  },
  "sort": [
    1586777122335
  ]
}

标准字段

event.severity 字段是数值，可以用来按级别排序事件，例如 Kibana 查询 event.severity <= 4 将获取所有日志级别为 Warning 或更严重的信息。

错误字段

如果日志消息包含异常，详细信息将在错误字段中报告。

自定义字段

根据 ECS 规范，这些使用交替的大写字母，以识别它们为非标准字段。

标签值

标签值可以通过其键访问，例如如果消息或作用域包括一个参数 CustomerId，则值将记录为 labels.CustomerId 可在 Kibana 中使用 "labels.CustomerId: 12345" 进行搜索。

示例

以下将生成两个标签，labels.EndTime 来自消息，labels.CustomerId 来自作用域

using (_logger.BeginScope("{CustomerId}", customerId))
{
  _logger.LogWarning("End of processing reached at {EndTime}.", end);
}

标签从消息（状态）和任何作用域值中获取（可能通过配置选项禁用）。在 Microsoft.Extensions.Logging 中，内部 FormattedLogValues 在 ILogger 过载的日志级别和作用域中使用；它实现了 IEnumerable<KeyValuePair<string, object>> 接口，用于提取单个参数值。

在 ECS 中的 labels 属性不应包含嵌套对象，因此值被转换为关键字字符串。对于大多数对象，这只需调用 ToString()，对于某些类型的特定格式，例如在列表上调用字符串通常不是很有用，因此记录列表的内容。

标签值格式化

（1）请参阅 https://docs.microsoft.com/en-us/dotnet/standard/datetime/choosing-between-datetime

代理字段

这些标识正在使用的记录器提供器的版本。

服务字段

这标识了正在运行并生成日志的应用程序/服务。

获取值的方式是从入口装配中抽取的，使用Assembly.GetEntryAssembly()，根据Name和AssemblyInformationalVersionAttribute的值（如果有设置为信息版本，否则使用装配的Version）。

注意：您应该使用正确设置装配信息版本的构建过程。例如，如果您使用git的dotnet项目，可以安装本地工具GitVersion.Tool，并使用它自动从git分支信息生成语义版本号。

安装工具

dotnet new tool-manifest
dotnet tool install GitVersion.Tool

然后使用该工具创建在构建过程中可以使用的语义版本号

dotnet tool restore
dotnet gitversion

您可以使用本仓库中的build.ps1脚本作为示例。

跟踪字段

ASP.NET会自动在层之间传递关联标识符；从3.0起，它还支持W3C跟踪上下文标准（https://www.w3.org/TR/trace-context/）。

Activity.Current.RootId的值用作跨服务标识符（在W3C格式中这是跟踪ID），如果在W3C格式中，则使用Activity.Current.Id中Span ID部分作为交易的值，否则使用完整值（这与ASP.NET的工作方式一致）。

建议启用W3C格式，以提高与其他系统的兼容性

Activity.DefaultIdFormat = ActivityIdFormat.W3C;

宿主字段

注意：可以通过配置禁用。

进程字段

注意：可以通过配置禁用。

用户字段

注意：可以通过配置禁用。