ApsaraDB for ClickHouse:Java 可観測性データを Cloud Database ClickHouse Enterprise Edition にエクスポート

ステップ 1：OpenTelemetry Collector のデプロイ

1. ECS インスタンスを構成します。

   1. ECS インスタンスを購入します。パブリックネットワークアクセスのために、購入時にパブリック IP アドレスを割り当てることを推奨します。

   2. ECS インスタンスの IP アドレスを Alibaba Cloud ClickHouse の許可リストに追加します。

      • プライベート IP アドレス：ECS インスタンスと Alibaba Cloud ClickHouse Enterprise Edition インスタンスが同一の Virtual Private Cloud (VPC) 内にある場合、ECS インスタンスのプライベート IP アドレスを許可リストに追加します。この場合、以下の手順で Alibaba Cloud ClickHouse インスタンスの VPC エンドポイントを使用します。

      • パブリック IP アドレス：ECS インスタンスがプライベートネットワーク経由で Alibaba Cloud ClickHouse Enterprise Edition インスタンスに接続できない場合、ECS インスタンスのパブリック IP アドレスを許可リストに追加します。この場合、以下の手順で Alibaba Cloud ClickHouse インスタンスのパブリックエンドポイントを使用します。

      ECS インスタンスに接続し、次のコマンドを実行して Alibaba Cloud ClickHouse インスタンスへの接続をテストできます。Ok. という応答が返された場合、接続は成功しています。

      curl http://cc-xxxxxxx-clickhouse.clickhouseserver.pre.rds.aliyuncs.com:8123

2. ECS インスタンスに接続し、次のコマンドを実行して otelcol-contrib をインストールします。

   mkdir llm-demo
   cd llm-demo
   wget -O otelcol-contrib.rpm https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.136.0/otelcol-contrib_0.136.0_linux_amd64.rpm
   yum install otelcol-contrib.rpm

3. OpenTelemetry Collector を構成し、gRPC および HTTP 経由で可観測性データを受信し、HTTP 経由で Alibaba Cloud ClickHouse インスタンスに送信できるようにします。

   次のコマンドをコピーし、以下のように設定を変更してください。

   • receivers セクションでは、OTLP レシーバーの endpoint を、ご利用の OpenTelemetry Collector サービスのエンドポイントに置き換えることを推奨します。

   • exporters セクションでは、次のように設定します。

     • ご利用の Alibaba Cloud ClickHouse インスタンスの接続情報を設定します。これには endpoint、username、および password が含まれます。

     • ご利用の Alibaba Cloud ClickHouse インスタンス内に可観測性データを保存するためのデータベース名およびテーブル名を設定します。これには database、traces_table_name、logs_table_name、および metrics_tables が含まれます。

   cat > /etc/otelcol-contrib/config.yaml << EOF
   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   processors:
     batch:
       timeout: 5s
       send_batch_size: 5000
   exporters:
     clickhouse:
       endpoint: http://cc-xxxxxx-clickhouse.clickhouseserver.pre.rds.aliyuncs.com:8123?dial_timeout=10s&compress=lz4&async_insert=1
       username: test
       password: password
       # ttl: 72h
       traces_table_name: otel_traces
       logs_table_name: otel_logs
       metrics_tables:
         gauge: 
           name: otel_metrics_gauge
         sum: 
           name: otel_metrics_sum
         summary: 
           name: otel_metrics_summary
         histogram: 
           name: otel_metrics_histogram
         exponential_histogram: 
           name: otel_metrics_exp_histogram
       create_schema: false
       timeout: 5s
       database: clickobserve_service
       sending_queue:
         queue_size: 1000
       retry_on_failure:
         enabled: true
         initial_interval: 5s
         max_interval: 30s
         max_elapsed_time: 300s
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [clickhouse]
       metrics:
         receivers: [otlp]
         processors: [batch]
         exporters: [clickhouse]
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [clickhouse]
   EOF

4. OpenTelemetry Collector を起動します。

   service otelcol-contrib restart

ステップ 2：Java アプリケーションの作成

このセクションでは、シンプルな Spring Boot サイコロロールサービスを例として使用します。

1. Java 環境を構成します。

   1. Java 環境をデプロイします。Java 17 以降のインストールを推奨します。

   2. Gradle をダウンロードおよびインストールします。Gradle 8 以降のインストールを推奨します。

2. Gradle プロジェクトを初期化します。

   この例では、ディレクトリ名を java-simple とします。初期化後、ディレクトリ構造は次のようになります。

   java-simple
   ├── app
   │   ├── build.gradle.kts
   │   └── src
   │       ├── main
   │       │   ├── java
   │       │   │   └── org
   │       │   │       └── example
   │       │   │           └── App.java
   │       │   └── resources
   │       └── test
   │           ├── java
   │           │   └── org
   │           │       └── example
   │           │           └── AppTest.java
   │           └── resources
   ├── gradle
   │   ├── libs.versions.toml
   │   └── wrapper
   │       ├── gradle-wrapper.jar
   │       └── gradle-wrapper.properties
   ├── gradle.properties
   ├── gradlew
   ├── gradlew.bat
   └── settings.gradle.kts

3. java-simple ディレクトリ内で、次のファイルを修正または作成します。

   build.gradle.kts

   plugins {
     id("java")
     id("org.springframework.boot") version "3.0.6"
     id("io.spring.dependency-management") version "1.1.0"
   }
   sourceSets {
     main {
       java.setSrcDirs(setOf("."))
     }
   }
   repositories {
     mavenCentral()
   }
   dependencies {
     implementation("org.springframework.boot:spring-boot-starter-web")
   }
   

   App.java

   package org.example;
   import org.springframework.boot.Banner;
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   @SpringBootApplication
   public class App {
     public static void main(String[] args) {
       SpringApplication app = new SpringApplication(App.class);
       app.setBannerMode(Banner.Mode.OFF);
       app.run(args);
     }
   }

   RollController.java

   package org.example;
   import java.util.Optional;
   import java.util.concurrent.ThreadLocalRandom;
   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestParam;
   import org.springframework.web.bind.annotation.RestController;
   @RestController
   public class RollController {
     private static final Logger logger = LoggerFactory.getLogger(RollController.class);
     @GetMapping("/rolldice")
     public String index(@RequestParam("player") Optional<String> player) {
       int result = this.getRandomNumber(1, 6);
       if (player.isPresent()) {
         logger.info("{} is rolling the dice: {}", player.get(), result);
       } else {
         logger.info("Anonymous player is rolling the dice: {}", result);
       }
       return Integer.toString(result);
     }
     public int getRandomNumber(int min, int max) {
       return ThreadLocalRandom.current().nextInt(min, max + 1);
     }
   }

ステップ 3：OpenTelemetry Java エージェントの構成

1. OpenTelemetry Java エージェントをダウンロードします。

   curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

2. 環境変数を構成します。

   export JAVA_TOOL_OPTIONS="-javaagent:/../opentelemetry-javaagent.jar" \
     OTEL_TRACES_EXPORTER=otlp \
     OTEL_METRICS_EXPORTER=otlp \
     OTEL_LOGS_EXPORTER=otlp \
     OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
     OTEL_EXPORTER_OTLP_ENDPOINT=http://<IP_ADDRESS>:4318 \
     OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://<IP_ADDRESS>:4318/v1/traces \
     OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<IP_ADDRESS>:4318/v1/metrics \
     OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://<IP_ADDRESS>:4318/v1/logs \
     OTEL_METRIC_EXPORT_INTERVAL=15000

   • JAVA_TOOL_OPTIONS：この値を opentelemetry-javaagent.jar ファイルの実際のパスに設定します。

   • エンドポイントの設定：http://<IP_ADDRESS>:4318 の <IP_ADDRESS> を、Java アプリケーションからアクセス可能な Otel Collector サービスエンドポイントの IP アドレスに置き換えます。

   • その他のパラメーターについては、「properties-exporters」をご参照ください。

ステップ 4：Java アプリケーションの起動とアクセス

1. プロジェクトのアプリケーションディレクトリで、次のコマンドを実行してアプリケーションを起動します。

   この例では、プロジェクトのアプリケーションディレクトリは ../java-simple/app です。

   gradle assemble
   java -jar ./build/libs/app.jar

2. ブラウザで http://<IP_ADDRESS>:8080/rolldice にアクセスします。<IP_ADDRESS> を、Java アプリケーションを実行しているサーバーの IP アドレスに置き換えます。

   リクエストが成功すると、ページに乱数が表示されます。例を以下に示します。

   5

ステップ 5：可観測性データのクエリと分析

1. Cloud Database ClickHouse インスタンスの詳細ページ左側のナビゲーションウィンドウで、ClickStack をクリックし、画面の指示に従ってサービスポータルを開きます。

2. メインページで、Java アプリケーションからの可観測性データをクエリおよび分析します。

   HyperDX の 検索 ページで、データソースを otel_traces に設定します。SELECT Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName という SQL クエリを入力し、ソート順を Timestamp DESC に設定します。左側の フィルター パネルで、SpanName（例：GET /rolldice または PUBLISH）および ServiceName（例：app または langgenius/dify）でフィルターをかけます。結果テーブルには、Timestamp、service、level、duration、SpanName などの列が表示され、サービス間のスパンのレイテンシー詳細が確認できます。