インストールしたサーバーの監視

Last updated
Tags Server v2.x サーバー管理者
CircleCI Server version 2.x は、リリースのサポートが終了しています。 リリースがサポートされているバージョンへのアップグレードについては、お客様のアカウントチームにご相談ください。

ここでは、インストールした CircleCI Server v2.x を監視するためのメトリクスについて説明します。

メトリクスの概要

メトリクスとは、監視と分析を目的として収集される技術的な統計データのことです。 このデータには、CPU やメモリの使用率などの基本情報のほか、実行済みビルド数や内部エラー数といった高度なデータも含まれます。 メトリクスを活用すると、以下のことが可能になります。

  • インシデントや異常な動作をすばやく検出する

  • コンピューティング リソースを動的にスケールする

  • インフラ全体の問題をさかのぼって把握する

CircleCI Server におけるメトリクスの仕組み

CircleCI Server v2.x.では、メトリクス収集用の主要コンポーネントとして、 Telegraf を使用しています。 Telegraf は、CircleCI サービスによって生成されたメトリクスデータを Datadog や AWS CloudWatch などのデータ監視プラットフォームに転送するサーバーソフトウェアです。

メトリクス名
Figure 1. メトリクス

CircleCI Server v2.x では、以下のようにメトリクスが収集されます。

  • サーバーの各コンポーネントが Services マシン上で動作する Telegraf コンテナにメトリクスデータを送信する。

  • Telegraf がポート 8125/UDP をリッスンし、全コンポーネントからのデータを受信 (入力) した後、事前に設定されたフィルターを適用してデータを保持するか破棄するかを判断する。

  • 一部のメトリクスタイプでは、Telegraf 内にデータが保持され、最大値、最小値、平均、標準偏差、合計などの統計データを定期的に計算する。

  • 最後に、Telegraf が Serveces マシン上の標準出力や、Datadog や AWS CloudWatch などの設定されたシンク (出力) にデータを送信する。

Telegraf は複数の入出力タイプを同時に受け取ることができるため、管理者は 1 つの Telegraf インスタンスで複数のメトリクス データセットを収集し、Datadog と CloudWatch の両方に転送することが可能です。

メトリクスの標準設定

以下のコマンドで、メトリクスの設定ファイルを確認します。

sudo docker inspect --format='{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}' telegraf | grep telegraf.conf | awk '{ print $1 }' | xargs cat

このファイルには 4 つの注目すべきブロックがあります (管理コンソールの設定によっては、いくつかのブロックがない場合もあります )。

  • [[inputs.statsd]] – Input configuration to receive metrics data through 8125/UDP (as discussed above)

  • [[outputs.file]] – Output configuration to emit metrics to stdout. 受け取ったメトリクスはすべて、Telegraf の Docker ログに表示されるように設定されています。 メトリクスの設定をデバッグする際に役立ちます。

  • [[outputs.cloudwatch]] – Output configuration to emit metrics to CloudWatch

  • [[outputs.datadog]] – Output configuration to emit metrics to Datadog

この設定ファイルは、Replicated (CircleCI Server v2.x を管理およびデプロイするためのサービス) によって自動的に生成され、管理もすべて Replicated が行います。 この標準の設定をカスタマイズしたい場合は、変更したいブロックを挿入*しない*ように Replicated を設定します。

ファイルを直接変更しないでください。 直接行った変更は、サービスの再起動などの特定のイベントでは Replicated によって破棄されます。 For example, if a customized [[inputs.statsd]] block is added without stopping automatic interpolation, you will encounter errors as Telegraf attempts to listen to 8125/UDP twice, and the second attempt will fail with EADDRINUSE.

メトリクスのカスタマイズを行わない標準的な設定では、必要なのは上述の設定のみす。 `/etc/circleconfig/telegraf`の下にファイルを置いてメトリクスのカスタマイズを設定した場合、その設定はメインの設定に追加されます。つまり、メインの設定とカスタマイズファイルの内容がすべて連結されるのです。 メトリクスのカスタマイズに関する詳細は、 [custom-metrics] のセクションを参照してください。

システム監視のメトリクス

AWS Cloudwatch または Datadog のいずれかへのメトリクス転送を有効にするには、 [supported-platforms] セクションで使用するサービスの手順に従います。 以下のセクションでは、CircleCI Server 環境で利用可能なメトリクスの概要を説明します。

VM サービスと Docker のメトリクス

VM サービスと Docker サービスのメトリクスは、メトリクスの収集とレポート用プラグイン駆動型サーバーエージェントである Telegraf によって転送されます。

以下のメトリクスが有効化されています。

Nomad ジョブのメトリクス

Nomad ジョブのメトリクスは、Nomad サーバーエージェントによって有効化され、送信されます。 レポートされるメトリクスは、以下の 5 つです。

Metric 説明

circle.nomad.server_agent.poll_failure

Nomad エージェントの最後のポーリングが失敗した場合は 1、成功した場合は 0 を返します。

circle.nomad.server_agent.jobs.pending

クラスター全体の保留中ジョブの総数を返します。

circle.nomad.server_agent.jobs.running

クラスター全体の実行中ジョブの総数を返します。

circle.nomad.server_agent.jobs.complete

クラスター全体の完了済みジョブの総数を返します。

circle.nomad.server_agent.jobs.dead

クラスター全体の停止中ジョブの総数を返します。

Nomad メトリクスのコンテナが正常に動作している場合、標準出力や標準エラーには何も出力されません。 障害が発生すると、標準エラーにメッセージが出力されます。

CircleCI のメトリクス

CircleCI Server v2. 18 からサポート

circle.backend.action.upload-artifact-error

アーティファクトのアップロードに失敗した回数をトラックします。

circle.build-queue.runnable.builds

システムを経由するビルドのうち実行可能と見なされているビルドの数をトラックします。

circle.dispatcher.find-containers-failed

1.0 ビルドの数をトラックします。

circle.github.api_call

CircleCI が GitHub に対して実行している API 呼び出しの回数をトラックします。

circle.http.request

CircleCi のリクエストへの応答コードをトラックします。

circle.nomad.client_agent.*`

Nomad クライアントのメトリクスをトラックします。

circle.nomad.server_agent.*

存在する Nomad サーバーの数をトラックします。

circle.run-queue.latency

実行可能なビルドが待機している時間をトラックします。

circle.state.container-builder-ratio

Builder ごとのコンテナの数をトラックします (1.0 のみ)。

circle.state.lxc-available

利用可能なコンテナの数をトラックします (1.0 のみ)。

circle.state.lxc-reserved

予約/使用中のコンテナの数をトラックします (1.0 のみ)。

circleci.cron-service.messaging.handle-message

cron-service によって処理される RabbitMQ メッセージのタイミングと数を通知します。

circleci.grpc-response

grpc システムが呼び出すシステムの待機時間をトラックします。

サポート対象プラットフォーム

メトリクスと監視用に組み込まれているプラットフォームは、AWS CloudWatch と DataDog の2つです。 以下のセクションでは、それぞれの有効化と設定について説明します。

AWS CloudWatch

AWS CloudWatch を有効にするには、以下の作業を行ってください。

  1. 管理コンソールの設定ページに移動します。 お客様の CircleCI の URL の代わりに下記 URL を使用します: your-circleci-hostname.com:8800/settings#cloudwatch_metrics

  2. AWS CloudWatch Metrics の下で [Enable (有効にする)] をクリックして設定を開始します。

    1. Cloudwatch の有効化 image::metrics_aws_cloudwatch1.png[AWS CloudWatch]

AWS CloudWatch の設定

設定には、2つのオプションがあります。

  • Services Box の [IAM Instance Profile (IAM インスタンスプロファイル)] を使用し、カスタムの領域と名前空間を設定する方法

    Configuration IAM
    Figure 2. CloudWatchの領域と名前空間
  • カスタムの領域と名前空間と共に、AWS のアクセスキーとシークレットキーを使用する方法

    Configuration Alt
    Figure 3. アクセスキーとシークレットキー

設定の保存後、AWS CloudWatch コンソールに移動すると、メトリクスが転送されていることを*確認*できます。

DataDog

Datadogを有効にするには、以下の作業を行ってください。

  1. 管理コンソールの設定ページに移動します。 お客様の CircleCI の ホスト名の代わりに下記 URL を使用します: your-circleci-hostname.com:8800/settings#datadog_metrics

  2. Datadog Metrics の下で [Enable (有効にする)] をクリックして設定を開始します。

    Enable DataDog
    Figure 4. Datadog メトリクスの有効化
  3. Datadog API キーを入力します。 Datadog のメトリクスサマリーに移動すると、メトリクスが転送されていることを確認できます。

    DataDog API Key
    Figure 5. Datadog API キーの入力

カスタムメトリクス

Telegraf の設定ファイルを使用したカスタムメトリクスにより、Replicated に Datadog や AWS Cloudwatch への標準メトリクスの転送を許可するよりも、より細かく制御することができます。

サーバーのメトリクスの基本設定には、基本的な使用の場合のみが想定されています。 メトリクスの扱い方をカスタマイズすると、以下の際に有益です。

  • メトリクスデータをご希望のプラットフォーム (ご自身の InfluxDB インスタンスなど)に転送する。

  • 特定のイベントを検出するために、追加のメトリクスを監視する。

  • データ分析プラットフォームに送信するメトリクス数の削減(グロスオペレーションコストの削減)。

1. 標準メトリクスの設定を無効にする

Disable Replicated’s interpolation of the Telegraf configuration to fully customize and outputs:

  1. 管理コンソールを開きます。

  2. Settings ページで、 Custom Metrics セクションに移動し、[Use custom telegraf metrics (Telegraf のカスタムメトリクスを使用する)]オプションを有効にします。

    Custom Metrics
    Figure 6. カスタムメトリクス
  3. スクロールダウンして変更を保存し、サービスを再起動します。

サービスの再起動の際にダウンタイムが発生します。 無効にした後は、Replicated の設定に関わらず、Datadog や CloudWatch への出力を手動で設定する必要があります。

2. カスタム設定を作成する

これで Telegraf のすべてのサポート機能を実行する準備が整いました。 あとは Telegraf の有効な設定ファイルを入力するだけです。

  1. Services マシンに SSH で接続します。

  2. /etc/circleconfig/telegraf/statsd.conf に以下を追加します。

    [[inputs.statsd]]
            service_address = ":8125"
            parse_data_dog_tags = true
            metric_separator = "." namepass = []
  3. namepass の下に、受信したいメトリクスを追加します。以下の例では、上記のリストの上から4つのみを設定しています。 (その他の設定例は下記を参照してください)。

    [[inputs.statsd]]
            service_address = ":8125"
            parse_data_dog_tags = true
            metric_separator = "." namepass = [
                "circle.backend.action.upload-artifact-error",
                "circle.build-queue.runnable.builds",
                "circle.dispatcher.find-containers-failed",
                "circle.github.api_call"
              ]
  4. `sudo docker restart telegraf`を実行して、Telegraf コンテナを再起動します。

詳細な設定方法については、 Telegraf の README を参照してください。

Telegraph の設定例

シナリオ 1: 2 つの InfluxDB インスタンスに標準メトリクスを記録する

下記の例では、デフォルトのメトリクスを2つの InfluxDB インスタンスに記録します。一つは InfluxDB オンプレミスサーバー (your-influx-db-instance.example.com)、もう一つは InfluxDB Cloud 2 です。

[[inputs.statsd]]
  service_address = ":8125"
  parse_data_dog_tags = true
  metric_separator = "." namepass = [
    "circle.backend.action.upload-artifact-error",
    "circle.build-queue.runnable.builds",
    "circle.dispatcher.find-containers-failed",
    "circle.github.api_call",
    "circle.http.request",
    "circle.nomad.client_agent.*",
    "circle.nomad.server_agent.*",
    "circle.run-queue.latency",
    "circle.state.container-builder-ratio",
    "circle.state.lxc-available",
    "circle.state.lxc-reserved",
    "circle.vm-service.vm.assigned-vm",
    "circle.vm-service.vms.delete.status",
    "circle.vm-service.vms.get.status",
    "circle.vm-service.vms.post.status",
    "circleci.cron-service.messaging.handle-message",
    "circleci.grpc-response"
  ]

[[outputs.influxdb]]
  url = "http://your-influx-db-instance.example.com:8086"
  database = "circleci"

[[outputs.influxdb_v2]]
  urls = ["https://us-central1-1.gcp.cloud2.influxdata.com"]
  token = "YOUR_TOKEN_HERE"
  organization = "circle@example.com"
  bucket = "circleci"
シナリオ 2: すべてのメトリクスを Datadog に記録する

標準設定では選択されたメトリクスしか扱えないため、Telegraf により廃棄されるメトリクスが多くあります。 JVM 統計やコンテナごとの CPU 使用率などの廃棄された高度なデータを受信したい場合は、namepass フィルタを外すことで、受信したすべてのメトリクスを保持することができます。 この例では、Datadog へのメトリクス送信を設定する方法も示しています。 前述したように、Replicated の設定に関わらず、Datadog への出力は手動で設定する必要があります。

このシナリオでは、大量のデータが発生します。
[[inputs.statsd]]
  service_address = ":8125"
  parse_data_dog_tags = true
  metric_separator = "." [[outputs.datadog]]
  apikey = 'YOUR_API_KEY_HERE'
シナリオ 3: 限られたメトリクスを CloudWatch に送る

AWS は、CloudWatch の料金をスカラーのシリーズごとに (つまり「平均」や「合計」のレベル) 請求します。 メトリクスのキー (例: circle.run-queue.latency) ごとに複数のフィールド (例:平均、最大値、最小値、合計) が計算され、冗長なフィールドもあるため、CloudWatch に送信するフィールドを選択することもできます。 This can be achieved by configuring [[outputs.cloudwatch]] with fieldpass. You also may declare [[outputs.cloudwatch]] multiple times to pick up multiple metrics, as illustrated below.

[[inputs.statsd]]
  # Accept all metrics at input level to 1) enable output configurations without thinking of inputs, and to 2) dump discarded metrics to stdout just in case.
  service_address = ":8125"
  parse_data_dog_tags = true
  metric_separator = "." [[outputs.cloudwatch]]
    # Fill in these two variables if you need to access CloudWatch with an IAM User, not an IAM Role attached to your Services box
    # access_key = 'ACCESS'
    # secret_key = 'SECRET'

    # Specify region for CloudWatch
    region = 'ap-northeast-1'
    # Specify namespace for easier monitoring
    namespace = 'my-circleci-server'

    # Name of metrics key to record
    namepass = ['circle.run-queue.latency']
    # Name of metrics field to record; key and field are delimited by an underscore (_)
    fieldpass = ['mean']

[[outputs.cloudwatch]]
    # Outputs can be specified multiple times.

    # Fill in these two variables if you need to access CloudWatch with an IAM User, not an IAM Role attached to your Services box
    # access_key = 'ACCESS'
    # secret_key = 'SECRET'

    # Specify region for CloudWatch
    region = 'ap-northeast-1'
    # Specify namespace for easier monitoring
    namespace = 'my-circleci-server'

    # Name of metrics key to record
    namepass = ['mem']
    # Name of metrics field to record; key and field are delimited by an underscore (_)
    fieldpass = ['available_percent']

その他のヒント

docker logs -f telegraf を実行してログをチェックすることで、設定した出力に出力プロバイダー (influx など) がリストされているかどうかを確認できます。 また、お使いの CircleCI Server システムのすべてのメトリクスが特定の環境にタグ付けされるようにするには、設定ファイルに以下のコードを記載します。

[global_tags]
Env="<staging-circleci>"

デフォルトの高度なインストール手順については、https://github.com/influxdata/influxdb#installation[InfluxDB のドキュメント]を参照してください。

設定を変更した場合、CircleCI アプリケーションの再起動が必要となり、ダウンタイムが発生します。


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか?

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。