SQL クエリレシーバー

はじめに

以下の手順に従って、コンポーネントの設定とアクティベーションを行ってください：

1. Splunk Distribution of the OpenTelemetry Collector をホストまたはコンテナプラットフォームにデプロイします：

   • インストーラ・スクリプトを使用して Linux 用 Collector をインストールします。

   • インストーラ・スクリプトを使用して Collector for Windows をインストールします。

   • Helmを使用してCollector for Kubernetesをインストールする

2. 次のセクションで説明するように、SQL クエリレシーバーを設定します。

3. Collector を再起動します。

サンプル構成

レシーバーをアクティブにするには設定ファイルの receivers セクションに sqlquery を追加します：

receivers:
  sqlquery:
    driver: your.driver
    datasource: "your_data_source"
    queries:
      - sql: "your_query"

次に、設定ファイルの service セクションの metrics パイプラインに、レシーバーを含めます：

service:
  pipelines:
    metrics:
      receivers: [sqlquery]

完全な設定例については「Example: Query a movie database」を参照してください。

TCPを使用したMySQLデータソースの設定例

これは、user@unix(/mysql/run/mysql.sock)/schema/autocommit=trueでオートコミットモードを有効にして、MySQLデータソースをソケット経由でデータベースに接続する例です：

receivers:
  sqlquery:
    driver: your.driver
    datasource: "user:password@tcp(host:port)/schema"
    queries:
      - sql: "your_query"

高度な設定

これらは、最も関連性の高い必須設定フィールドです：

• driverします。データベースドライバの名前。postgres、mysql、snowflake、sqlserver、hdb（SAP HANA）または oracle（Oracle DB）のいずれか。

• datasourceします。sql.Open に渡されるデータソース値。これは通常、少なくともデータベース名と接続情報で構成される、ドライバ固有の文字列です。これは、ドライバのドキュメントで「接続文字列」と呼ばれることがあります。たとえば、host=localhost port=5432 user=me password=s3cr3t sslmode=disable のようになります。

• queriesします。クエリのリストでのクエリとは、SQL ステートメントと 1 つ以上のログまたはメトリクスのセクションのことです。詳しくは「Perform queries」を参照してください。

以下のフィールドはオプションです。

• collection_interval。デフォルトでは 10s です。クエリの実行間隔。

• storage。デフォルトでは "" です。処理結果を追跡するために使用するストレージ拡張の ID。

• telemetryします。コンポーネント自身のテレメトリ（ログ、メトリクス、トレース）の設定を定義します。

• telemetry.logsします。コンポーネント自身のログの設定を定義します。

• telemetry.logs.query。デフォルトでは false です。true に設定すると、SQL クエリが実行されるたびに、クエリのテキストとパラメータの値が「Running query」というデバッグログとともに記録されます。

設定の一覧は「設定」を参照してください。

クエリの実行

クエリは、SQL ステートメントと 1 つ以上のログまたはメトリクスのセクションで構成されます。

• 少なくとも 1 つのログまたは 1 つのメトリクスセクションが必要です。

• 技術的には、ログとメトリクスの両方のセクションを 1 つのクエリセクションに入れることは可能ですが、ログとメトリクスのクエリの要件はまったく異なります。

クエリメトリクス

各メトリクスのセクションは、metric_name、value_column、および追加のオプションフィールドで構成されます。クエリされた各メトリクスについて、SQL クエリは返される行ごとに 1 つの OTel メトリクスを生成します。

これらは、最も関連性の高い必須設定フィールドです：

• metric_nameします。OTel メトリクスに割り当てられた名前。

• value_columnします。メトリクスのデータポイントの値を設定するために使用する、返されたデータセット内のカラム名。Oracle DB などの一部のドライバでは、大文字と小文字が区別されます。

関連するオプションフィールドは以下の通りです：

• attribute_columnsします。データポイントの属性設定に使用される、返されたデータセット内の列名のリスト。Oracle DB などの一部のドライバでは、大文字と小文字が区別されます。

• data_typeします。gauge（デフォルト）または sum。詳しくは「 メトリクスタイプ」を参照してください。

• value_typeします。int（デフォルト）または double。

• monotonic。デフォルトでは false です。累積和の値が単調増加するかどうかを示すブール値。ロールオーバーやリセットは行われません。

• aggregationします。cumulative（デフォルト）または delta。sum メトリクスタイプにのみ適用されます。

• descriptionします。メトリクスに適用される説明。

• unitします。メトリクスに適用される単位。

• static_attributesします。メトリクスに適用される静的属性。

• start_ts_columnします。開始タイムスタンプを含むカラムの名前で、その値がメトリクスの開始タイムスタンプに適用され、その値がなければ現在の時刻が 使用されます。sum メトリクスタイプにのみ適用されます。

• ts_columnします。タイムスタンプを含むカラムの名前で、その値がメトリクスのタイムスタンプに適用されます。 これは、最後に記録されたメトリックのデータポイントの時刻に応じて、現在のタイムスタンプになります。

例：映画データベースのクエリ

SQL クエリレシーバーを使用して、データベースから情報をプルできます。

例えば、映画とそのジャンルのリストがある映画データベースがあるとします：

count(*) クエリは、ジャンル別に分類された映画を返します：

以下の設定を使用する場合：

receivers:
  sqlquery:
    driver: postgres
    datasource: "host=localhost port=5432 user=postgres password=s3cr3t sslmode=disable"
    storage: file_storage
    queries:
      - sql: "select count(*) as count, genre from movie group by genre"
        metrics:
          - metric_name: movie.genres
            value_column: "count"
            attribute_columns: ["genre"]
            static_attributes:
              dbinstance: mydbinstance

設定のクエリは、各収集間隔で 2 つのメトリクスを返します。

メトリクス#0

• 記述子

  • 名前： movie.genres

  • DataType: Gauge

• NumberDataPoints #0

• データポイント属性：

  • genre: STRING(sci-fi)

  • dbinstance: STRING(mydbinstance)

• 値：2

メトリクス#1

• 記述子

  • 名前： movie.genres

  • DataType: Gauge

• NumberDataPoints #0

• データポイント属性：

  • genre: STRING(action)

  • dbinstance: STRING(mydbinstance)

• 値：1

例： oracle ドライバで映画データベースを照会します。

Oracle DB ドライバを使って接続し、前の例と同じテーブルスキーマと内容を照会します。

sqlquery:
  # driver name: oracle
  # username: otel
  # password: password
  # host: localhost
  # container exposed port: 51521
  # Oracle DB service name: XE
  # Refer to Oracle Go Driver go_ora documentation for full connection string options
  datasource: "oracle://otel:password@localhost:51521/XE"
  driver: oracle
  queries:
    # Note: The table name may need to be preceded by the name of the user who created the table.
    # If the table is created by an initialization script within a docker container, it would be referred
    # to as "sys.movie", as the sys user runs initialization scripts. Permission would need to be granted
    # to the "otel" user to access or modify the table in that case.
    # This example assumes "otel" created the movie table.
    - sql: "select count(*) as count, genre, avg(imdb_rating) as avg from otel.movie group by genre"
      metrics:
        - metric_name: genre.count
          # Note that COUNT and GENRE are now all capital letters, the queries will return nothing if this isn't
          # accounted for.
          value_column: "COUNT"
          attribute_columns: [ GENRE ]
        - metric_name: genre.imdb
          value_column: "AVG"
          attribute_columns: [ GENRE ]
          value_type: "double"

例：MySQL データソース形式

MySQL の datasource フォーマットは user:password@tcp(host:port)/databasename です。

NULL 値

次のことに留意してください：

• NULL の値を生成するクエリは警告を記録します。

• NULL 値を生成するカラムを参照する設定では、追加のエラーが記録されます。

どちらの場合でも、レシーバーは作動し続けます。

設定

次の表に、SQL クエリレシーバーの設定オプションを示します。

トラブルシューティング