検索ジョブ API について

ヘッダ

クエリ パラメータ

ステータス コード

応答ヘッダ

https://api.sumologic.com/api/v1/search/jobs/SEARCH_JOB_ID

結果

新たに作成された検索ジョブの ID を含む JSON ドキュメント。この ID は、検索ジョブに関連するすべての API インタラクションで使用します。

エラー応答の例:

{
  "status" : 400,
  "id" : "IUUQI-DGH5I-TJ045",
  "code" : "searchjob.invalid.timestamp.from",
  "message" : "The 'from' field contains an invalid time."
}

セッション例

以下のセッション例では cURL を使用しています。検索ジョブ API では、クライアント側で Cookie が有効であることが要件となります。curl -b cookies.txt -c cookies.txtoptions を使用して、API が設定した Cookie を受信、格納、および送り返します。

curl -b cookies.txt -c cookies.txt -H 'Content-type: application/json' 
-H 'Accept: application/json' -X POST -T createSearchJob.json 
--user <ACCESSID>:<ACCESSKEY> https://api.sumologic.com/api/v1/search/jobs

createSearchJob.json ファイルの内容は次のようになります。

{
  "query": "| count _sourceCategory",
  "from": "2019-05-03T12:00:00",
  "to": "2019-05-03T12:05:00",
  "timeZone": "IST",
  "byReceiptTime": true
}

Sumo Logic からの応答では、「ロケーション」ヘッダとして次の形式で検索ジョブ ID が返されます。 

https://api.sumologic.com/api/v1/search/jobs/SEARCH_JOB_ID

クエリ パラメータ

結果

結果は、検索ジョブ ステータス、現時点までに見つかったメッセージ件数、現時点までに生成されたレコード件数、保留中の警告やエラー、およびヒストグラム バケットを含む JSON ドキュメントです。

セッション例

curl -v --trace-ascii - -b cookies.txt -c cookies.txt -H 'Accept: application/json' 
--user <ACCESSID>:<ACCESSKEY> https://api.sumologic.com/api/v1/search/jobs/37589506F194FC80

フォーマットされた結果ドキュメントは次のようになります。

{
   "state":"DONE GATHERING RESULTS",
   "messageCount":90,
   "histogramBuckets":[
      {
         "length":60000,
         "count":1,
         "startTimestamp":1359404820000
      },
      {
         "length":60000,
         "count":1,
         "startTimestamp":1359405480000
      },
      ...
      {
         "length":60000,
         "count":1,
         "startTimestamp":1359404340000
      }
   ],
   "pendingErrors":[

   ],
   "pendingWarnings":[

   ],
   "recordCount":1
}

サンプル結果ジョブのステータスは DONE GATHERING RESULTS (結果の収集完了) になっています。返されるステータスを下表に示します。

結果の詳細

messageCount と recordCount の値は、現時点までに見つかったメッセージの件数と生成されたレコードの件数を示します。メッセージは未処理のログ メッセージで、レコードは集計データです。

aggregation operator を含まないクエリの場合はメッセージのみが返されます。クエリに集計が含まれる場合 (例: count by _sourceCategory) は (SQL データベースから返される結果と同じように) メッセージと集計結果のレコードの両方が返されます。

pendingErrors と pendingWarnings の値には、前回のステータスのリクエスト時から蓄積している保留中のエラー文字列または警告文字列が含まれます。

エラーと警告は保存されません。エラーや警告を取っておく必要がある場合は、ローカルに保存してください。

histogramBuckets 値には、ヒストグラム バケットのリストが返されます。ヒストグラム バケットは、バケット開始時のタイムスタンプ (ミリ秒数) とバケットの幅を表す長さ (ミリ秒数) で定義されます。timestampplus 長は、バケットの終了タイムスタンプであるため、カウントはバケット内のメッセージ数となります。

ヒストグラムに対応するヒストグラム バケットは、Sumo Logic のインタラクティブ アナリティクス API に表示されます。ヒストグラム バケットは保存されません。ステータス API は前回のステータス リクエスト以降に発見された新しいバケットしか返しませんので、バケットを使用する予定がある場合は、クライアント側で保存する必要があります。Sumo Logic バックエンドの検索ジョブは、常に指定された時間範囲の最後から最初に向かって、一致するメッセージを発見して処理することで実行されます。このプロセスにおいて、ヒストグラム バケットが検出されて返されます。

クエリ パラメータ

セッション例

curl -b cookies.txt -c cookies.txt -H 'Accept: application/json' 
--user <ACCESSID>:<ACCESSKEY> 'https://api.sumologic.com/api/v1/search/jobs/37589506F194FC80/messages?offset=0&limit=10'

フォーマットされた結果ドキュメントは次のようになります。

{
   "fields":[
      {
         "name":"_messageid",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_sourceid",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_sourcename",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_sourcehost",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_sourcecategory",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_format",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_size",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_messagetime",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_receipttime",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_messagecount",
         "fieldType":"int",
         "keyField":false
      },
      {
         "name":"_raw",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_source",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_collectorid",
         "fieldType":"long",
         "keyField":false
      },
      {
         "name":"_collector",
         "fieldType":"string",
         "keyField":false
      },
      {
         "name":"_blockid",
         "fieldType":"long",
         "keyField":false
      }
   ],
   "messages":[
      {
         "map":{
            "_receipttime":"1359407350899",
            "_source":"service",
            "_collector":"local",
            "_format":"plain:atp:o:0:l:29:p:yyyy-MM-dd HH:mm:ss,SSS ZZZZ",
            "_blockid":"-9223372036854775669",
            "_messageid":"-9223372036854773763",
            "_messagetime":"1359407350333",
            "_collectorid":"1579",
            "_sourcename":"/Users/christian/Development/sumo/ops/assemblies/latest/service-20.1-SNAPSHOT/logs/service.log",
            "_sourcehost":"Chiapet.local",
            "_raw":"2013-01-28 13:09:10,333 -0800 INFO  [module=SERVICE] [logger=util.scala.zk.discovery.AWSServiceRegistry] [thread=pool-1-thread-1] FINISHED findRunningInstances(ListBuffer((Service: name: elasticache-1, defaultProps: Map()), (Service: name: userAndOrgCache, defaultProps: Map()), (Service: name: rds_cloudcollector, defaultProps: Map()))) returning Map((Service: name: elasticache-1, defaultProps: Map()) -> [], (Service: name: userAndOrgCache, defaultProps: Map()) -> [], (Service: name: rds_cloudcollector, defaultProps: Map()) -> []) after 1515 ms",
            "_size":"549",
            "_sourcecategory":"service",
            "_sourceid":"1640",
            "_messagecount":"2044"
         }
      },
      ...
      {
         "map":{
            "_receipttime":"1359407051885",
            "_source":"service",
            "_collector":"local",
            "_format":"plain:atp:o:0:l:29:p:yyyy-MM-dd HH:mm:ss,SSS ZZZZ",
            "_blockid":"-9223372036854775674",
            "_messageid":"-9223372036854773772",
            "_messagetime":"1359407049529",
            "_collectorid":"1579",
            "_sourcename":"/Users/christian/Development/sumo/ops/assemblies/latest/service-20.1-SNAPSHOT/logs/service.log",
            "_sourcehost":"Chiapet.local",
            "_raw":"2013-01-28 13:04:09,529 -0800 INFO  [module=SERVICE] [logger=com.netflix.config.sources.DynamoDbConfigurationSource] [thread=pollingConfigurationSource] Successfully polled Dynamo for a new configuration based on table:raychaser-chiapetProperties",
            "_size":"246",
            "_sourcecategory":"service",
            "_sourceid":"1640",
            "_messagecount":"2035"
         }
      }
   ]
}

結果の詳細

結果には fields と messages の 2 つのリストがあります。

• fields には、返された各メッセージで定義されているすべてのフィールドのリストが含まれます。各フィールドについて、フィールド名とフィールド タイプが返されます。
• messages には、マップのリストが含まれ、各メッセージについて 1 つのマップとなります。各マップは、fields に含まれるフィールドからメッセージの実際の値にマップします。

たとえば、_raw フィールドには、収集された未処理のログメッセージが含まれます。

_messagetime は、メッセージ自身から抽出したタイムスタンプの、エポック時刻からのミリ秒数です。

_receipttime は、メッセージが Sumo Logic システムに到着したタイムスタンプの、エポック時刻からのミリ秒数です。

Sumo Logic でも使用されているメタデータ フィールドの _sourcehost、_sourcename、および _sourcecategory は、ここでも使用されます。

クエリ パラメータ

セッション例

curl -b cookies.txt -c cookies.txt -H 
'Accept: application/json' --user <ACCESSID>:<ACCESSKEY>
'https://api.sumologic.com/api/v1/search/jobs/37589506F194FC80/records?offset=0&limit=1'

フォーマットされた結果ドキュメントは次のようになります。

{
   "fields":[
      {
         "name":"_sourcecategory",
         "fieldType":"string",
         "keyField":true
      },
      {
         "name":"_count",
         "fieldType":"int",
         "keyField":false
      }
   ],
   "records":[
      {
         "map":{
            "_count":"90",
            "_sourcecategory":"service"
         }
      }
   ]
}

返されるドキュメントは、メッセージ ページング API と同様です。返されるレコードのスキーマは、fields 要素の一部であるフィールド リストによって記述されます。レコード自身はマップのリストです。

クエリ パラメータ

セッション例

curl -b cookies.txt -c cookies.txt -X DELETE 
-H 'Accept: application/json' --user <ACCESSID>:<ACCESSKEY> 
https://api.sumologic.com/api/v1/search/jobs/37589506F194FC80