# PromQL 查询
<a name="CloudWatch-PromQL-Querying"></a>

您通过 OpenTelemetry Protocol（OTLP）将 OpenTelemetry 指标摄取到 CloudWatch 时，分层 OTLP 数据模型会扁平化为兼容 PromQL 的标签。本节介绍标签结构、用于查询这些标签的 PromQL 语法以及 PromQL 中对 UTF-8 的支持。

**注意**  
Prometheus 3 中的 PromQL 支持在指标名称和标签名称中使用完整的 UTF-8 字符。这对于 OTLP 指标尤其重要，因为 OpenTelemetry 语义惯例在属性名称中使用点号，例如 `service.name`。以前，这些点号在翻译过程中被下划线所取代，这会导致 OTel 惯例中定义的内容与 Prometheus 中可查询的内容之间存在差异。

在 CloudWatch 中使用 PromQL 时，`@` 前缀惯例会将 OTLP 范围的标签与标准 Prometheus 标签区分开来。每个作用域内的字段使用双 `@` 前缀（例如 `@resource.@schema_url`），而属性使用单 `@` 作用域前缀，例如 `@resource.service.name`。数据点属性还支持裸露（无前缀）访问，以向后兼容标准 PromQL 查询，例如 `{"http.server.active_requests"}` 和 `{"@datapoint.@name"="http.server.active_requests"}` 等效。

PromQL 表达式用花括号括起来，用于指定指标名称和一组可选的标签匹配器。以下示例选择了 `http.server.active_requests` 指标的所有时间序列：

```
{"http.server.active_requests"}
```

以下示例选择了 `http.server.active_requests` 指标的所有时间序列，其中 OpenTelemetry 资源属性 `service.name` 等于 `myservice`：

```
{"http.server.active_requests", "@resource.service.name"="myservice"}
```

您可以在单个查询中组合多个标签匹配器。以下示例选择了 `http.server.active_requests` 指标的所有时间序列，其中在所有美国区域，OpenTelemetry 资源属性 `service.name` 等于 `myservice`：

```
{"http.server.active_requests",
 "@resource.service.name"="myservice",
 "@aws.region"=~"us-.*"}
```

以下示例显示了范围查询。该示例计算每个时间序列在指定时间范围内所有数据点的平均值：

```
avg_over_time(
  {"http.server.active_requests",
   "@resource.service.name"="myservice"}[5m]
)
```

下表总结了每个 OTLP 范围的前缀惯例：


| OTLP 范围 | 字段前缀 | 属性前缀 | 示例 | 
| --- | --- | --- | --- | 
| 资源 | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` | 
| 埋点作用域 | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` | 
| 数据点 | `@datapoint.@` | `@datapoint.` 或裸露 | `cpu="cpu0"` 或 `@datapoint.cpu="cpu0"` | 
| Amazon 保留 | 不适用 | `@aws.` | `@aws.account_id="123456789"` | 

## 使用 PromQL 查询 Amazon 已出售指标
<a name="CloudWatch-PromQL-Querying-Vended"></a>

为了能够在 PromQL 中查询 Amazon 已出售指标，您首先需要启用已出售指标的 OTel 补充功能。请参阅：[在 PromQL 中启用已出售指标](CloudWatch-OTelEnrichment.md)。

启用 OTel 补充功能后，可通过 PromQL 使用其他标签查询 Amazon 已出售指标。指标名称与原始 CloudWatch 指标名称相同，原始 CloudWatch 维度可作为数据点属性提供。以下标签可用（以下示例适用于 EC2 实例）：


| PromQL 标签 | 说明 | 示例 | 
| --- | --- | --- | 
| `InstanceId` | 原始 CloudWatch 维度，作为数据点属性 | `i-0123456789abcdef0` | 
| `"@resource.cloud.resource_id"` | 资源的完整 ARN | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` | 
| `"@resource.cloud.provider"` | 云提供商 | `aws` | 
| `"@resource.cloud.region"` | 此指标起源的 Amazon 区域 | `us-east-1` | 
| `"@resource.cloud.account.id"` | 此指标起源的 Amazon 账户 ID | `123456789012` | 
| `"@instrumentation.@name"` | 标识源服务的埋点作用域名称 | `cloudwatch.aws/ec2` | 
| `"@instrumentation.cloudwatch.source"` | 源服务标识符 | `aws.ec2` | 
| `"@instrumentation.cloudwatch.solution"` | 补充解决方案标识符 | `CloudWatchOTelEnrichment` | 
| `"@aws.tag.Environment"` | Amazon 资源标签 | `production` | 
| `"@aws.account"` | 摄取此指标的 Amazon 账户（系统标签） | `123456789012` | 
| `"@aws.region"` | 摄取此指标的 Amazon 区域（系统标签） | `us-east-1` | 

以下示例为特定的 Lambda 函数选择了 `Invocations`：

```
histogram_sum({Invocations, FunctionName="my-api-handler"})
```

以下示例为具有特定团队标签的所有函数选择了 `Errors` Lambda：

```
histogram_sum(
  {Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}
)
```

以下示例计算按团队分组的 `Invocations` Lambda 总数：

```
sum by ("@aws.tag.Team")(
    {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)
```

以下示例选择了 EC2 `CPUUtilization` 指标的所有时间序列。`"@instrumentation.@name"="cloudwatch.aws/ec2"` 的用法是为了专门匹配来自 EC2 的 CPUUtilization，而不是来自其他 Amazon 服务（例如 Amazon Relational Database Service）的 CPUUtilization：

```
histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
```