的版本 4 (V4) 适用于 .NET 的 Amazon SDK 已经发布！

有关重大更改和迁移应用程序的信息，请参阅[迁移主题](https://docs.amazonaws.cn/sdk-for-net/v4/developer-guide/net-dg-v4.html)。

 [https://docs.amazonaws.cn/sdk-for-net/v4/developer-guide/net-dg-v4.html](https://docs.amazonaws.cn/sdk-for-net/v4/developer-guide/net-dg-v4.html)

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 可观测性
可观测性

宣布推出可观测性的 GA 版本

可观测性是指可以根据系统发出的数据推断出其当前状态的程度。发出的数据通常称为遥测。

 适用于 .NET 的 Amazon SDK 可以提供两种常见的遥测信号、指标和轨迹以及日志记录。您可以连接[TelemetryProvider](https://docs.amazonaws.cn/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html)以将遥测数据发送到可观测性后端（例如或 [Amazon X-Ray](https://docs.amazonaws.cn/xray/?icmpid=docs_homepage_devtools)A [ma](https://docs.amazonaws.cn/cloudwatch/?icmpid=docs_homepage_mgmtgov) zon CloudWatch），然后对其进行操作。

默认情况下，SDK 中的遥测信号处于禁用状态。本主题介绍如何启用和配置遥测输出。

## 其他资源


有关启用和使用可观测性的更多信息，请参阅以下资源：
+ [OpenTelemetry](https://opentelemetry.io/)
+ 博客文章《[增强可观察性 适用于 .NET 的 Amazon SDK 》 OpenTelemetry](https://www.amazonaws.cn/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/)
+ 博客文章[宣布 Amazon .NET OpenTelemetry 库正式上市](https://www.amazonaws.cn/blogs/dotnet/announcing-the-general-availability-of-aws-net-opentelemetry-libraries/)。
+ [的出口商 OpenTelemetry](https://opentelemetry.io/docs/languages/net/exporters/)
+ 有关可观测性的示例 Amazon Tools for PowerShell，请参阅《[ PowerShell 用户工具](https://docs.amazonaws.cn/powershell/latest/userguide/)指南》中的[可观察性](https://docs.amazonaws.cn/powershell/latest/userguide/observability.html)。

## 配置 `TelemetryProvider`


您可以在应用程序中为所有服务客户端或单个客户端全局配置 `TelemetryProvider`，如以下示例所示。[遥测提供商](observability-telemetry-providers.md)一节提供了有关遥测实现的信息，包括有关随 SDK 提供的实现的信息。

### 配置默认的全局遥测提供程序


默认情况下，每个服务客户端都尝试使用全局可用的遥测提供程序。这样，您只需设置一次提供程序，所有客户端都会使用它。此操作只需执行一次，且必须在创建任何服务客户端之前进行。

以下代码片段展示了如何设置全局遥测提供程序。然后，它会创建一个 Amazon S3 服务客户端，并尝试执行失败的操作。该代码向应用程序添加追踪记录和指标。此代码使用以下 NuGet 软件包：`OpenTelemetry.Exporter.Console`和`OpenTelemetry.Instrumentation.AWS`。

**注意**  
如果您使用身份 Amazon IAM Identity Center 验证，请务必同时添加`AWSSDK.SSO`和`AWSSDK.SSOOIDC`。

```
using Amazon.S3;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

Sdk.CreateTracerProviderBuilder()
    .ConfigureResource(e => e.AddService("DemoOtel"))
    .AddAWSInstrumentation()
    .AddConsoleExporter()
    .Build();

Sdk.CreateMeterProviderBuilder()
    .ConfigureResource(e => e.AddService("DemoOtel"))
    .AddAWSInstrumentation()
    .AddConsoleExporter()
    .Build();

var s3Client = new AmazonS3Client();

try
{
    var listBucketsResponse = await s3Client.ListBucketsAsync();
    // Attempt to delete a bucket that doesn't exist.
    var deleteBucketResponse = await s3Client.DeleteBucketAsync("amzn-s3-demo-bucket");
}
catch (Exception ex)
{
    Console.WriteLine(ex.Message);
}

Console.Read();
```

### 为特定服务客户端配置遥测提供程序


您可以为单个服务客户端配置特定的遥测提供程序（而不是全局遥测提供程序）。为此，请使用服务客户端构造函数的 Config 对象的 `TelemetryProvider` 类。例如，请参阅 [AmazonS3Config](https://docs.amazonaws.cn/sdkfornet/v4/apidocs/items/S3/TS3Config.html) 并找到 `TelemetryProvider` 属性。有关自定义遥测实现的信息，请参阅[遥测提供商](observability-telemetry-providers.md)。

**Topics**
+ [

## 其他资源
](#observability-resources)
+ [

## 配置 `TelemetryProvider`
](#observability-conf-telemetry-provider)
+ [

# Metrics
](observability-metrics.md)
+ [

# 遥测提供商
](observability-telemetry-providers.md)

# Metrics


下表列出了 SDK 发出的遥测指标。[配置遥测提供程序](observability.md#observability-conf-telemetry-provider)以使指标可观察。


**发布了哪些指标？**  

| 指标名称 | 单位 | 类型 | Attributes | 描述 | 
| --- | --- | --- | --- | --- | 
| client.call.持续时间 | s | 直方图 | rpc.service，rpc.m | 总体呼叫时长（包括重试次数、发送或接收请求和响应正文的时间） | 
| 客户机正常运行时间 | s | 直方图 | rpc. 服务 | 自创建客户机以来的时间长度 | 
| client.call.tept | \$1尝试\$1 | MonotonicCounter | rpc.service，rpc.m | 单个操作的尝试次数 | 
| client.call.errors | \$1错误\$1 | MonotonicCounter | rpc.service、rpc.method、excep | 某项操作的错误数 | 
| client.call.tempt\$1duration | s | 直方图 | rpc.service，rpc.m | 连接到服务、发送请求以及取回 HTTP 状态码和标头所花费的时间（包括等待发送的排队时间） | 
| client.call.resolve\$1endpoint\$1持续时间 | s | 直方图 | rpc.service，rpc.m | 为请求解析终端节点（终端节点解析器，不是 DNS）所花费的时间 | 
| client.call.serialization\$1dur | s | 直方图 | rpc.service，rpc.m | 序列化消息正文所花费的时间 | 
| client.call.derization\$1duration\$1 | s | 直方图 | rpc.service，rpc.m | 反序列化消息正文所花费的时间 | 
| client.col.auth.signing\$1duration | s | 直方图 | rpc.service，rpc.m | 签署请求所花费的时间 | 
| client.col.auth.resolve\$1identity\$1duration | s | 直方图 | rpc.service，rpc.m | 从身份提供商处获取身份（例如 Amazon 凭证或持有者令牌）所花费的时间 | 
| client.http.bytes\$1sent | 方式 | MonotonicCounter | 服务器地址 | HTTP 客户端发送的总字节数 | 
| client.http.bytes\$1receiv | 方式 | MonotonicCounter | 服务器地址 | HTTP 客户端接收的总字节数 | 

以下是各列的描述：
+ **指标名称**-发出的指标的名称。
+ **单位**-指标的计量单位。单位以 UC [UM](https://unitsofmeasure.org/ucum) 区分大小写 (“c/s”) 表示法给出。
+ **类型**-用于捕获指标的仪器类型。
+ **属性**-与指标一起发出的一组属性（维度）。
+ **描述**-对指标所衡量内容的描述。

# 遥测提供商


SDK 提供了[OpenTelemetry](https://opentelemetry.io/)作为遥测提供商的实现，[下一节](observability-telemetry-providers-otel.md)将对此进行介绍。

如果您有特定的遥测要求，已经在考虑遥测解决方案，或者需要精细控制遥测数据的捕获和处理方式，则也可以实现自己的遥测提供程序。

在[TelemetryProvider](https://docs.amazonaws.cn/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html)课堂上注册你自己的实现。以下是如何注册自己的`TracerProvider`和的简单示例`MeterProvider`。

```
using Amazon;
using Amazon.Runtime.Telemetry;
using Amazon.Runtime.Telemetry.Metrics;
using Amazon.Runtime.Telemetry.Tracing;

public class CustomTracerProvider : TracerProvider
{
    // Implement custom tracing logic here
}
public class CustomMeterProvider : MeterProvider
{
    // Implement custom metrics logic here
}

// Register custom implementations
AWSConfigs.TelemetryProvider.RegisterTracerProvider(new CustomTracerProvider());
AWSConfigs.TelemetryProvider.RegisterMeterProvider(new CustomMeterProvider());
```

**Topics**
+ [OpenTelemetry](observability-telemetry-providers-otel.md)

# 配置 OpenTelemetry基于遥测的提供商
OpenTelemetry

 适用于 .NET 的 Amazon SDK 包括 OpenTelemetry基于遥测提供程序的实现。有关如何将此提供程序设置为全局遥测提供程序的详细信息，请参阅[配置 `TelemetryProvider`](observability.md#observability-conf-telemetry-provider)。要使用此遥测提供程序，您需要以下项目资源：
+ .Instrum [OpenTelemetryentation.aws](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AWS) NuGet 软件包。
+ 遥测导出器，例如 OTLP 或控制台。有关更多信息，请参阅 OpenTelemetry文档[中的](https://opentelemetry.io/docs/languages/net/exporters/)导出器。

可以对 SDK 中包含的 OpenTelemetry 实现进行配置，以减少对 HTTPS 请求、凭证和压缩的跟踪量。为此，请将 `SuppressDownstreamInstrumentation` 选项设置为 `true`，类似于以下内容：

```
Sdk.CreateTracerProviderBuilder()
    .ConfigureResource(e => e.AddService("DemoOtel"))
    .AddAWSInstrumentation(options => options.SuppressDownstreamInstrumentation = true)
    .AddConsoleExporter()
    .Build();
```

有关此提供商的更多信息，请参阅 with [中的博客文章 “ 适用于 .NET 的 Amazon SDK 增强可观察性](https://www.amazonaws.cn/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/)”。 OpenTelemetry