PromQL クエリ

OpenTelemetry Protocol (OTLP) 経由で OpenTelemetry メトリクスを CloudWatch に取り込むと、階層 OTLP データモデルは PromQL 互換ラベルにフラット化されます。このセクションでは、ラベル構造、これらのラベルをクエリするための PromQL 構文、および PromQL での UTF-8 サポートについて説明します。

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"}

次の例では、OpenTelemetry リソース属性 http.server.active_requests が service.name に等しいメトリクス myservice のすべての時系列を選択します。

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

1 つのクエリで複数のラベルマッチャーを組み合わせることができます。次の例では、OpenTelemetry リソース属性 service.name がすべての米国リージョンで myservice に等しい http.server.active_requests メトリクスのすべての時系列を選択します。

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

以下に、範囲クエリの例を示します。各時系列の指定された時間範囲内のすべてのデータポイントの平均値を計算します。

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

次の表は、各 OTLP スコープのプレフィックス規則をまとめたものです:

PromQL を使用した提供された AWS メトリクスのクエリ

PromQL で提供された AWS メトリクスをクエリできるようにするには、まず提供されたメトリクスの OTel エンリッチメントを有効にする必要があります。以下を参照してください: PromQL で提供されたメトリクスを有効にする。

OTel エンリッチメントを有効にすると、提供された AWS メトリクスは、ラベルが追加されて PromQL 経由でクエリ可能になります。メトリクス名は元の CloudWatch メトリクス名と同じで、元の CloudWatch ディメンションはデータポイント属性として使用できます。次のラベルを使用できます (以下の例は EC2 インスタンス用です)。

次の例では、特定の Lambda 関数の Invocations を選択します。

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

次の例では、特定のチームでタグ付けされたすべての関数の Lambda Errors を選択します。

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

次の例では、チーム別にグループ化された Lambda Invocations の合計を計算します。

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

次の例では、EC2 CPUUtilization メトリクスのすべての時系列を選択します。"@instrumentation.@name"="cloudwatch.aws/ec2" の使用法は、Amazon Relational Database Service などの他の AWS のサービスではなく、EC2 からの CPUUtilization と排他的に一致させることです。

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