PrometheusとGrafanaでの監視

メトリクスの保存とデータの可視化にPrometheusGrafanaを使用している場合、Solrにはメトリクスやその他のデータを収集するためのPrometheusエクスポーターが含まれています。

PrometheusエクスポーターはSolrの完全なディストリビューションに含まれており、prometheus-exporter/にあります。slimSolrディストリビューションには含まれていません。

Prometheusエクスポーター(solr-exporter)を使用すると、メトリクスAPIから取得されるSolrメトリクスだけでなく、ファセットカウント、Collections APIコマンドへのレスポンス、およびPingリクエストも監視できます。

この図はより詳細なビューを提供します

image
図1. solr-exporterの図

solr-exporterを実行するには、3つの側面があります。

  • 収集するデータを定義するには、solr-exporter-config.xmlを変更します。Solrには使用できるデフォルト構成がありますが、エクスポーターを初めて実行する前に変更する場合は、以下のエクスポーター構成のセクションを参照してください。

  • Solr内からエクスポーターを起動します。以下のエクスポーターの起動のセクションを参照してください。

  • 正しいポートでリッスンするようにPrometheus構成を変更します。以下のPrometheus構成のセクションを参照してください。

エクスポーターの起動

solr-exporterを開始するには、prometheus-exporter/ディレクトリから./bin/solr-exporter(Linux)または.\bin\solr-exporter.cmd(Windows)を実行します。

solr-exporterによって公開されるメトリクスは、メトリクスエンドポイントhttps://127.0.0.1:8983/solr/admin/metricsで確認できます。

オペレーティングシステムとSolrのオペレーティングモードに応じて、以下のコマンドを参照してください。

Linux

ユーザー管理/シングルノード
$ cd prometheus-exporter
$ ./bin/solr-exporter -p 9854 -b https://127.0.0.1:8983/solr -f ./conf/solr-exporter-config.xml -n 8
SolrCloud
$ cd prometheus-exporter
$ ./bin/solr-exporter -p 9854 -z localhost:2181/solr -f ./conf/solr-exporter-config.xml -n 16

Windows

ユーザー管理/シングルノード
> cd prometheus-exporter
> .\bin\solr-exporter.cmd -p 9854 -b https://127.0.0.1:8983/solr -f .\conf\solr-exporter-config.xml -n 8
SolrCloud
> cd prometheus-exporter
> .\bin\solr-exporter -p 9854 -z localhost:2181/solr -f .\conf\solr-exporter-config.xml -n 16

コマンドラインパラメーター

Prometheusエクスポーターで利用可能なパラメーターのリスト。すべてのパラメーターは、コマンドラインではなく環境変数を介して指定できます。

h--help

オプション

デフォルト:なし

コマンドラインのヘルプと使用法を表示します。

-p--port$PORT

オプション

デフォルト:8989

Prometheusが新しいデータをリッスンするポート。このポートはPrometheusを構成するために使用されます。サーバーで使用されていない任意のポートを使用できます。

-b--baseurl$SOLR_URL

オプション

デフォルト:説明を参照

Solrがユーザー管理のクラスターまたはシングルノード構成で実行されている場合の、SolrのベースURL(例:https://127.0.0.1:8983/solr)。SolrCloudを実行している場合は、このパラメータを指定しないでください。-bパラメータと-zパラメータのどちらも定義されていない場合、デフォルトは-b https://127.0.0.1:8983/solrになります。

-z--zkhost$ZK_HOST

オプション

デフォルト:説明を参照

SolrがSolrCloudで実行されている場合の、ZooKeeper接続文字列(例:localhost:9983、またはlocalhost:2181/solr)。ユーザー管理のクラスターまたはシングルノード構成を実行している場合は、このパラメータを指定しないでください。-bパラメータと-zパラメータのどちらも定義されていない場合、-bパラメータのデフォルトが使用されます。

-f--config-file$CONFIG_FILE

オプション

デフォルト:prometheus-exporter/conf/solr-exporter-config.xml

読み取るSolrメトリクスを定義する構成ファイルへのパス。

-n--num-threads$NUM_THREADS

オプション

デフォルト:1

スレッド数。solr-exporterはSolrへのリクエスト用にスレッドプールを作成します。スレッド数を増やすことで、リクエストのレイテンシを改善できます。

-s--scrape-interval$SCRAPE_INTERVAL

オプション

デフォルト:60

Solrからメトリクスを収集する間隔(秒単位)。solr-exporterは、この設定によって制御される間隔でSolrからメトリクスを収集します。これらのメトリクスはキャッシュされ、Prometheusがこのツールからメトリクスをプルする頻度に関係なく返されます。スクレイプ間隔を短縮することでメトリクスの鮮度を向上させることができますが、メトリクス収集はコストがかかり、Solrにpingするための任意の検索を実行する可能性があるため、非常に低い値に設定しないでください。

-i--cluster-id$CLUSTER_ID

オプション

デフォルト:説明を参照

監視するクラスタの一意のID。このIDは、すべてのメトリクスにcluster_idラベルとして追加され、同じPrometheusインスタンスにレポートする複数のSolrクラスタを操作する場合、Grafanaダッシュボードでフィルターとして使用できます。このオプションを省略した場合、デフォルトではbaseUrlまたはzkHostのハッシュがIDとして使用されます。

-u--credentials$CREDENTIALS

オプション

デフォルト:なし

username:password形式で資格情報を指定します。例:--credentials solr:SolrRocks

環境変数オプション

Prometheus Exporterに付属の./binスクリプトは、以下の環境変数を介したカスタムJavaオプションの使用をサポートしています。

JAVA_HEAP

オプション

デフォルト:512m

初期(Xms)および最大(Xmx)のJavaヒープサイズを設定します。

JAVA_MEM

オプション

デフォルト:なし

カスタムJavaメモリ設定(例:-Xms1g -Xmx2g)。JAVA_HEAPが指定されている場合は無視されます。

GC_TUNE

オプション

デフォルト:-XX:+UseG1GC

カスタムJavaガベージコレクション設定。

JAVA_OPTS

オプション

デフォルト:なし

追加のJVMオプション。

ZK_CREDS_AND_ACLS

オプション

デフォルト:なし

ACLで保護されたZooKeeperホストに接続するための資格情報。この変数に含める内容の詳細については、「SolrスクリプトにおけるZooKeeper ACL」のセクション、または以下の「セキュリティ保護されたSolrCloudからメトリクスを取得する」の例を参照してください。

CLASSPATH_PREFIX

オプション

デフォルト:なし

solr-exporterの起動時にロードする追加のライブラリの場所。

./binスクリプトを使用する場合、すべてのコマンドラインパラメータを環境変数を介して提供できます。

セキュリティ保護されたSolrCloudからメトリクスを取得する

SolrCloudのセキュリティ構成は、SolrJを使用する他のクライアントと同様に、環境変数を使用してsolr-exporterに注入できます。これは、メインスクリプトが環境変数オプションをピックアップしてJavaプロセスに渡すため可能です。

次の例では、基本認証プラグインSSL、およびZooKeeperアクセス制御で保護されたSolrCloudインスタンスを想定しています。

Solrの基本認証資格情報を含むbasicauth.propertiesファイルがあると仮定します。

httpBasicAuthUser=myUser
httpBasicAuthPassword=myPassword

次に、次のようにExporterを起動できます(Linux)。

$ cd prometheus-exporter
$ export JAVA_OPTS="-Djavax.net.ssl.trustStore=truststore.p12 -Djavax.net.ssl.trustStorePassword=truststorePassword -Dsolr.httpclient.builder.factory=org.apache.solr.client.solrj.impl.PreemptiveBasicAuthClientBuilderFactory -Dsolr.httpclient.config=basicauth.properties"
$ export ZK_CREDS_AND_ACLS="-DzkCredentialsProvider=org.apache.solr.common.cloud.VMParamsSingleSetCredentialsDigestZkCredentialsProvider -DzkDigestUsername=readonly-user -DzkDigestPassword=zkUserPassword"
$ export CLASSPATH_PREFIX="../server/solr-webapp/webapp/WEB-INF/lib/commons-codec-1.11.jar"
$ ./bin/solr-exporter -p 9854 -z zk1:2181,zk2:2181,zk3:2181 -f ./conf/solr-exporter-config.xml -n 16
注意

ExporterにはSSL/基本認証用のcommons-codecライブラリが必要ですが、付属していません。したがって、この例ではSolr Webアプリケーションから再利用しています。もちろん、別のソースを使用することもできます。

Exporter構成

solr-exporterの構成は、Solrから取得するデータを定義します。これにはメトリクスが含まれますが、PingRequestHandler、Collections API、および任意のクエリリクエストハンドラへのクエリを含めることもできます。

デフォルトの構成例はprometheus-exporter/conf/solr-exporter-config.xmlにあります。以下は、それを少し短縮したバージョンです。

<config>

  <rules>

    <ping>
      <lst name="request">
        <lst name="query">
          <str name="path">/admin/ping</str>
        </lst>
        <arr name="jsonQueries">
          <str>
            . as $object | $object |
            (if $object.status == "OK" then 1.0 else 0.0 end) as $value |
            {
              name         : "solr_ping",
              type         : "GAUGE",
              help         : "See following URL: https://solr.dokyumento.jp/guide/solr/latest/deployment-guide/ping.html",
              label_names  : [],
              label_values : [],
              value        : $value
            }
          </str>
        </arr>
      </lst>
    </ping>

    <metrics>
      <lst name="request">
        <lst name="query">
          <str name="path">/admin/metrics</str>
          <lst name="params">
            <str name="group">all</str>
            <str name="type">all</str>
            <str name="prefix"></str>
            <str name="property"></str>
          </lst>
        </lst>
        <arr name="jsonQueries">
          <!--
            jetty metrics
          -->
          <str>
            .metrics["solr.jetty"] | to_entries | .[] | select(.key | startswith("org.eclipse.jetty.server.handler.DefaultHandler")) | select(.key | endswith("xx-responses")) as $object |
            $object.key | split(".") | last | split("-") | first as $status |
            $object.value.count as $value |
            {
            name         : "solr_metrics_jetty_response_total",
            type         : "COUNTER",
            help         : "See following URL: https://solr.dokyumento.jp/guide/solr/latest/deployment-guide/metrics-reporting.html",
            label_names  : ["status"],
            label_values : [$status],
            value        : $value
            }
          </str>
...
        </arr>
      </lst>
    </metrics>

    <collections>
      <lst name="request">
        <lst name="query">
          <str name="path">/admin/collections</str>
          <lst name="params">
            <str name="action">CLUSTERSTATUS</str>
          </lst>
        </lst>
        <arr name="jsonQueries">
          <str>
            .cluster.live_nodes | length as $value|
            {
              name         : "solr_collections_live_nodes",
              type         : "GAUGE",
              help         : "See following URL: https://solr.dokyumento.jp/guide/solr/latest/deployment-guide/cluster-node-management.html#clusterstatus",
              label_names  : [],
              label_values : [],
              value        : $value
            }
          </str>
...
        </arr>
      </lst>
    </collections>

    <search>
      <lst name="request">
        <lst name="query">
          <str name="collection">collection1</str>
          <str name="path">/select</str>
          <lst name="params">
            <str name="q">*:*</str>
            <str name="start">0</str>
            <str name="rows">0</str>
            <str name="json.facet">
              {
                category: {
                  type: terms,
                  field: cat
                }
              }
            </str>
          </lst>
        </lst>
        <arr name="jsonQueries">
          <str>
            .facets.category.buckets[] as $object |
            $object.val as $term |
            $object.count as $value |
            {
              name         : "solr_facets_category",
              type         : "GAUGE",
              help         : "Category facets",
              label_names  : ["term"],
              label_values : [$term],
              value        : $value
            }
          </str>
        </arr>
      </lst>
    </search>

  </rules>

</config>

構成タグと要素

solr-exporterは、構成ファイル内の定義に従ってSolrにリクエストを行い、レスポンスをスクレイピングし、Prometheusが理解できるJSON構造に変換することで機能します。構成ファイルは、リクエストする要素、それらをスクレイピングする方法、および抽出されたデータをJSONテンプレートのどこに配置するかを定義します。

solr-exporter構成ファイルは、常に2つの単純な要素で始まり、閉じられます。

<config>
  <rules>

  </rules>
</config>

これらの要素の間には、solr-exporterがリクエストする必要があるデータが定義されています。実行できるリクエストには、いくつかの種類があります。

<ping>

Pingリクエストへの応答をスクレイピングします。

<metrics>

メトリクスAPIリクエストへの応答をスクレイピングします。

<collections>

コレクションAPIリクエストへの応答をスクレイピングします。

<search>

クエリリクエストへの応答をスクレイピングします。

これらの各タイプ内で、クエリとレスポンスの処理方法を定義する必要があります。これを行うには、さらに2つの要素を定義します。

<query>

リクエストに使用されるクエリパラメータを定義します。このセクションでは、クエリを定義するためにいくつかの追加プロパティを使用します。

collection

オプション

デフォルト:なし

クエリを発行するコレクション。SolrCloudクラスタでのみ使用されます。

core

オプション

デフォルト:なし

クエリを発行するコア。ユーザー管理のクラスタまたはシングルノード構成でのみ使用されます。

path

オプション

デフォルト:なし

リクエストが送信されるクエリエンドポイントへのパス。例としては、admin/metrics/select、またはadmin/collectionsなどがあります。

params

オプション

デフォルト:なし

追加のクエリパラメータ。これらは、リクエストタイプとエンドポイントによって異なります。たとえば、メトリクスエンドポイントを使用している場合、特定のグループまたはプレフィックスにクエリを制限するパラメータを追加できます。Collections APIを使用している場合、使用するコマンドはパラメータになります。

<jsonQueries>

jq構文で1つ以上のJSONクエリを定義する配列です。これらのクエリを構造化する方法の詳細については、jqユーザーマニュアルを参照してください。

jqクエリは、次の形式でJSONを出力する必要があります。

{
  "name": "solr_ping",
  "type": "GAUGE",
  "help": "See following URL: https://solr.dokyumento.jp/guide/solr/latest/deployment-guide/ping.html",
  "label_names": ["base_url","core"],
  "label_values": ["https://127.0.0.1:8983/solr","collection1"],
  "value": 1.0
}

各プロパティにどのような情報を含めるべきか、および上記の例がPrometheus用にどのように変換されるかの例については、以下のExposition Formatセクションを参照してください。

Exposition Format

solr-exporterはJSONを次のエキスポジション形式に変換します。

# TYPE <name> <type>
# HELP <name> <help>
<name>{<label_names[0]>=<label_values[0]>,<label_names[1]>=<labelvalues[1]>,...} <value>

次のパラメータを設定する必要があります。

name

設定するメトリック名。詳細については、Prometheusの命名に関するベストプラクティスを参照してください。

type

メトリクスのタイプ。COUNTERGAUGESUMMARYHISTOGRAM、またはUNTYPEDを指定できます。詳細については、Prometheusのメトリクスタイプを参照してください。

help

メトリクスのヘルプテキスト。

label_names

メトリクスのラベル名。詳細については、Prometheusの命名に関するベストプラクティスを参照してください。

label_values

メトリクスのラベル値。詳細については、Prometheusの命名に関するベストプラクティスを参照してください。

value

メトリクスの値。値はDouble型に設定する必要があります。

たとえば、solr-exporterは前のセクションのJSONを次のように変換します。

# TYPE solr_ping gauge
# HELP solr_ping See following URL: https://solr.dokyumento.jp/guide/solr/latest/deployment-guide/ping.html
solr_ping{base_url="https://127.0.0.1:8983/solr",core="collection1"} 1.0

Prometheus構成

Prometheusは、ダウンロードしてデプロイする必要がある別のサーバーです。詳細については、Prometheusのはじめにページを参照してください。

Prometheusがsolr-exporterについて知るためには、次の例のように、Prometheusサーバーのprometheus.yml構成ファイルにリッスンアドレスを追加する必要があります。

scrape_configs:
  - job_name: 'solr'
    static_configs:
      - targets: ['localhost:9854']

すでにscrape_configsのセクションがある場合は、同じセクションにjob_nameとその他の値を追加できます。

設定をPrometheusに適用すると、Prometheusはsolr-exporterからSolrのメトリクスをプルし始めます。

Prometheusサーバー、solr-exporter、およびSolrが連携して動作しているかどうかをテストするには、https://127.0.0.1:9090にアクセスし、Prometheus GUIでsolr_pingメトリクスのクエリを実行します。

image
図2. Prometheus Solr Ping式

サンプルGrafanaダッシュボード

視覚化にGrafanaを使用するには、Grafanaを別途ダウンロードしてデプロイする必要があります。詳細については、Grafanaのドキュメントサイトを参照してください。Grafanaは、以前に設定したPrometheusサーバーを含む、多くのソースからデータを消費します。

Grafanaのサンプルダッシュボードは、次のJSONファイルで提供されています:prometheus-exporter/conf/grafana-solr-dashboard.json。このファイルを他のGrafanaダッシュボード構成とともに配置し、solr-exporter構成に対して行ったカスタマイズに応じて、必要に応じて変更できます。

ダッシュボードID 12456を使用して、Grafanaのインポート機能を使用することにより、grafana.com経由でSolrダッシュボードを直接インポートできます。

このスクリーンショットは、それがどのように見えるかを示しています。

image
図 3. Grafana ダッシュボード