Simple Log Service:Metricstore関連のHTTP APIの詳細

インスタントクエリAPI

Instant Queries APIは、指定された時点でのメトリックのクエリに使用されます。

GET https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/query
POST https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/query

次の表に変数を示します。

• サンプルコード

  curl -X GET 'https:// haoqi-sls-metric-test.pub-cn-hangzhou.log.aliyuncs.com/prometheus/haoqi-sls-metric-test/prometheus-metrics/api/v1/query?query=up&time=1676700699' \
  -uユーザー名: パスワード \
  -H「コンテンツタイプ: application/x-www-form-urlencoded」
  
  # ユーザー名とパスワードには、Alibaba CloudアカウントまたはRAMユーザーのAccessKeyペアを指定します。

• クエリと分析結果

  {
      "status": "success" 、
      "data": {
          "resultType": "vector" 、
          "result": [
              {
                  "metric": {
                      "__name__": "up" 、
                      "インスタンス": "demo.promlabs.com:10001" 、
                      "仕事": "デモ"
                  },
                  "value": [
                      1676700550.696,
                      "1"
                  ]
              },
              {
                  "metric": {
                      "__name__": "up" 、
                      "インスタンス": "demo.promlabs.com:10000" 、
                      "仕事": "デモ"
                  },
                  "value": [
                      1676700550.696,
                      "1"
                  ]
              }
          ]
      }
  }

範囲クエリAPI

Range Queries APIは、指定された時間範囲内の複数の時点でメトリクスをクエリするために使用されます。

GET https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/query_range
POST https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/query_range

次の表に変数を示します。

• サンプルコード

  次のサンプルコードは、2023-02-18 14:09:59から2023-02-18 14:16:39までのメトリックをクエリする方法の例を示しています。 間隔は60秒です。

  curl -X GET 'https://haoqi-sls-metric-test.pub-cn-hangzhou.log.aliyuncs.com/prometheus/haoqi-sls-metric-test/prometheus-metrics/api/v1/query_range?query=up&start=1676700599&end=1676700999&step=60s' \
  -u username:password \
  -H 'Content-Type: application/x-www-form-urlencoded'
  
  # Specify the AccessKey pair of an Alibaba Cloud account or a RAM user for the username and password.

• クエリと分析結果

  {
    "status": "success",
    "data": {
      "resultType": "matrix",
      "result": [
        {
          "metric": {
            "__name__": "up",
            "instance": "demo.promlabs.com:10000",
            "job": "demo"
          },
          "values": [
            [
              1676700599,
              "1"
            ],
            [
              1676700659,
              "1"
            ],
            [
              1676700719,
              "0"
            ],
            [
              1676700779,
              "0"
            ],
            [
              1676700839,
              "1"
            ],
            [
              1676700899,
              "0"
            ],
            [
              1676700959,
              "1"
            ]
          ]
        },
        {
          "metric": {
            "__name__": "up",
            "instance": "demo.promlabs.com:10001",
            "job": "demo"
          },
          "values": [
            [
              1676700599,
              "1"
            ],
            [
              1676700659,
              "1"
            ],
            [
              1676700719,
              "0"
            ],
            [
              1676700779,
              "0"
            ],
            [
              1676700839,
              "1"
            ],
            [
              1676700899,
              "1"
            ],
            [
              1676700959,
              "1"
            ]
          ]
        }
      ]
    }
  }

クエリシリーズAPI

クエリシリーズAPI操作は、指定された期間内に指定された条件を満たすすべてのメトリック名とラベルベースの数値ペアをクエリするために使用されます。

GET https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/series
POST https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/series

次の表に変数を示します。

• 設定例

  curl -g -X GET 'https://haoqi-sls-metric-test.pub-cn-hangzhou.log.aliyuncs.com/prometheus/haoqi-sls-metric-test/prometheus-metrics/api/v1/series?match[]=up{instance="demo.promlabs.com:10000"}&match[]=go_sched_latencies_seconds_bucket&start=1676700599&end=1676700999' \
  -u username:password \
  -H 'Content-Type: application/x-www-form-urlencoded'
  
  # Specify the AccessKey pair of an Alibaba Cloud account or a RAM user for the username and password.

• クエリと分析結果

  {
      "status": "success",
      "data": [
          {
              "__name__": "go_gc_duration_seconds_count",
              "instance": "demo.promlabs.com:10000",
              "job": "demo"
          },
          {
              "__name__": "go_gc_duration_seconds_count",
              "instance": "demo.promlabs.com:10001",
              "job": "demo"
          },
          {
              "__name__": "up",
              "instance": "demo.promlabs.com:10000",
              "job": "demo"
          }
      ]
  }

クエリラベル名API

[ラベル名の照会] APIは、指定された期間内に指定された条件を満たすすべてのラベル名を照会するために使用されます。

GET https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/labels
POST https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/labels

次の表に変数を示します。

• 設定例

  次のサンプルコードは、指定した期間内にすべてのメトリックのラベル名を照会する方法の例を示しています。

  curl -X GET 'https://haoqi-sls-metric-test.pub-cn-hangzhou.log.aliyuncs.com/prometheus/haoqi-sls-metric-test/prometheus-metrics/api/v1/labels?start=1676700599&end=1676700999' \
  -u username:password \
  -H 'Content-Type: application/x-www-form-urlencoded'
  
  # Specify the AccessKey pair of an Alibaba Cloud account or a RAM user for username and password.

• クエリと分析結果

  {
      "status": "success",
      "data": [
          "code",
          "instance",
          "job",
          "le",
          "method",
          "mode",
          "path",
          "quantile",
          "status",
          "type",
          "version",
          "__name__"
      ]
  }

クエリラベル値API

ラベル値の照会API操作は、指定された期間内に指定された条件を満たす指定されたラベル名のすべてのラベル値を照会するために使用されます。

GET https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}/api/v1/label/<label_name>/values

次の表に変数を示します。

• 設定例

  次のサンプルコードは、指定された期間内にupメトリックのインスタンスラベルのすべての値を照会する方法の例を示しています。

  curl -X GET 'https://haoqi-sls-metric-test.pub-cn-hangzhou.log.aliyuncs.com/prometheus/haoqi-sls-metric-test/prometheus-metrics/api/v1/label/instance/values?match[]=up&start=1676700599&end=1676700999' \
  -u username:password \
  -H 'Content-Type: application/x-www-form-urlencoded'
  
  # Specify the AccessKey pair of an Alibaba Cloud account or a RAM user for the username and password.

• クエリと分析結果

  {
      "status": "success",
      "data": [
          "demo.promlabs.com:10000",
          "demo.promlabs.com:10001",
          "demo.promlabs.com:10002"
      ]
  }

HTTPを介したクエリAPI操作の呼び出し

import (
	"flag"
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
	"strconv"
	"strings"
	"time"
)

const separator = "#"

func http_main() {

	project := flag.String("project", "xxxx", "")
	metricStore := flag.String("metricstore", "xxxx", "")
	endpoint := flag.String("endpoint", "xxxx", "")
	akId := flag.String("akid", "xxxx", "")
	akKey := flag.String("aksecret", "xxxx", "")
	query := flag.String("query", "avg(up)", "")
	queryType := flag.String("type", "values", "range or query or labels or values or series")
	matches := flag.String("match", "up", "") // Concatenate multiple parameters of the match[] method by using number signs (#). 
	labelName := flag.String("label", "instance", "")
	step := flag.String("step", "1m", "")
	fromtime := flag.String("from", "2023-02-15T00:00:00Z", "time 2006-01-02T15:04:05Z07:00")
	totime := flag.String("to", "2023-02-15T00:15:00Z", "time 2006-01-02T15:04:05Z07:00")

	flag.Parse()

	timeFrom, err := time.Parse(time.RFC3339, *fromtime)
	if err != nil {
		panic(err)
	}
	timeTo, err := time.Parse(time.RFC3339, *totime)
	if err != nil {
		panic(err)
	}

	// URL: https://{project}.{sls-enpoint}/prometheus/{project}/{metricstore}
	prometheusEndpoint := fmt.Sprintf("https://%s/prometheus/%s/%s", *project+"."+*endpoint, *project, *metricStore)

	var uri string
	urlVal := url.Values{}
	urlVal.Add("start", strconv.FormatInt(timeFrom.Unix(), 10))
	urlVal.Add("end", strconv.FormatInt(timeTo.Unix(), 10))

	switch *queryType {
	case "range":
		urlVal.Add("query", *query)
		urlVal.Add("step", *step)
		uri = fmt.Sprintf("%s/api/v1/query_range?%v", prometheusEndpoint, urlVal.Encode())
	case "query":
		urlVal.Add("query", *query)
		urlVal.Add("time", strconv.FormatInt(timeTo.Unix(), 10))
		uri = fmt.Sprintf("%s/api/v1/query?%v", prometheusEndpoint, urlVal.Encode())
	case "labels":
		extractAddMatches(*matches, urlVal)
		uri = fmt.Sprintf("%s/api/v1/labels?%v", prometheusEndpoint, urlVal.Encode())
	case "values":
		extractAddMatches(*matches, urlVal)
		uri = fmt.Sprintf("%s/api/v1/label/%s/values?%v", prometheusEndpoint, *labelName, urlVal.Encode())
	case "series":
		extractAddMatches(*matches, urlVal)
		uri = fmt.Sprintf("%s/api/v1/series?%v", prometheusEndpoint, urlVal.Encode())
	}

	req, _ := http.NewRequest(http.MethodGet, uri, nil)
	req.SetBasicAuth(*akId, *akKey)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	buf, err := ioutil.ReadAll(resp.Body)
	resp.Body.Close()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(buf))

}

func extractAddMatches(matches string, uVal url.Values) {
	splits := strings.Split(matches, separator)
	for _, match := range splits {
		uVal.Add("match[]", match)
	}
}

SDK for Prometheusを使用したクエリAPI操作の呼び出し

この例では、使用されているPrometheus用SDKのバージョンはv1.14.0です。 詳細については、「Prometheus client_golang」をご参照ください。

import (
	"context"
	"flag"
	"fmt"
	"github.com/prometheus/client_golang/api"
	v1 "github.com/prometheus/client_golang/api/prometheus/v1"
	"net"
	"net/http"
	"net/url"
	"time"
)

func main() {
	project := flag.String("project", "xxxx", "")
	metricStore := flag.String("metricstore", "xxxx", "")
	endpoint := flag.String("endpoint", "xxxx", "")
	akId := flag.String("akid", "xxxx", "")
	akKey := flag.String("aksecret", "xxxx", "")
	flag.Parse()

	// URL: https://{project}.{sls-enpoint}/prometheus/{project}/{metricstore}
	prometheusEndpoint := fmt.Sprintf("https://%s.%s/prometheus/%s/%s", *project, *endpoint, *project, *metricStore)

	client, err := api.NewClient(api.Config{
		Address: prometheusEndpoint,
		RoundTripper: &http.Transport{
			// set basic auth
			Proxy: func(req *http.Request) (*url.URL, error) {
				req.SetBasicAuth(*akId, *akKey)
				return nil, nil
			},
			DialContext: (&net.Dialer{
				Timeout:   60 * time.Second,
				KeepAlive: 60 * time.Second,
			}).DialContext,
			TLSHandshakeTimeout: 10 * time.Second,
		},
	})
	if err != nil {
		panic(err)
	}

	v1api := v1.NewAPI(client)
	ctx, _ := context.WithTimeout(context.Background(), 60*time.Second)
	r := v1.Range{
		Start: time.Now().Add(-15 * time.Minute),
		End:   time.Now(),
		Step:  time.Minute,
	}
	// query range
	result, warnings, err := v1api.QueryRange(ctx, "avg(up)", r)
	if err != nil {
		panic(err)
	}
	if len(warnings) > 0 {
		fmt.Printf("Warnings: %v %v\n", warnings, result)
	}
	fmt.Println(result)

	// query
	result, warnings, err = v1api.Query(ctx, "avg(up)", time.Now())
	if err != nil {
		panic(err)
	}
	if len(warnings) > 0 {
		fmt.Printf("Warnings: %v %v\n", warnings, result)
	}
	fmt.Println(result)

	// series
	series, warnings, err := v1api.Series(ctx, []string{"up"}, time.Now().Add(-15*time.Minute), time.Now())
	if err != nil {
		panic(err)
	}
	if len(warnings) > 0 {
		fmt.Printf("Warnings: %v %v\n", warnings, result)
	}
	fmt.Println(series)

	// labels
	names, warnings, err := v1api.LabelNames(ctx, []string{"up"}, time.Now().Add(-15*time.Minute), time.Now())
	if err != nil {
		panic(err)
	}
	if len(warnings) > 0 {
		fmt.Printf("Warnings: %v %v\n", warnings, result)
	}
	fmt.Println(names)

	// labelValues
	values, warnings, err := v1api.LabelValues(ctx, "instance", []string{"up"}, time.Now().Add(-15*time.Minute), time.Now())
	if err != nil {
		panic(err)
	}
	if len(warnings) > 0 {
		fmt.Printf("Warnings: %v %v\n", warnings, result)
	}
	fmt.Println(values)
}

認証失敗

次の情報が返された場合、認証は失敗します。 有効なAccessKeyペアを指定することを推奨します。

{
    "status": "error",
    "errorType": "unauthorized",
    "error": "get query instance error: {\n    \"httpCode\": 401,\n    \"errorCode\": \"Unauthorized\",\n    \"errorMessage\": \"AccessKeyId not found: xxxx\",\n    \"requestID\": \"xxxx\"\n}"
}

無効なPromQLステートメント

次の情報が返された場合、PromQLステートメントは無効です。 queryパラメーターで指定されているクエリ文を変更することを推奨します。

--> /api/v1/query_range?query=up[2m]&start=1676700599&end=1676700999&step=60s
{
    "status": "error",
    "errorType": "bad_data",
    "error": "invalid expression type \"range vector\" for range query, must be Scalar or instant Vector"
}

タイムアウトエラー

次の情報が返された場合、クエリはタイムアウトします。 timeoutパラメーターの値を増やすことを推奨します。

{
    "status": "error",
    "errorType": "timeout",
    "error": "query timed out in expression evaluation"
}

不完全なクエリ結果

次の情報が返された場合、クエリ結果は不完全です。 クエリの時間範囲を狭めて、再度クエリを実行することを推奨します。

{
    "status": "success",
    "data": {
        "resultType": "matrix",
        "result": [
            {
                "metric": {},
                "values": [
                    [
                        1673798460,
                        "11111111"
                    ],
                    [
                        1673799060,
                        "22222222"
                    ],
                    [
                        1673799660,
                        "33333333"
                    ]
                ]
            }
        ]
    },
    "warnings": [
        "Request to Sls partial incompleted, incomplete task count : 11, total : 108"
    ]
}