Simple Log Service:Details of Metricstore-related HTTP API

Instant Queries API

The Instant Queries API operation is used to query metrics at a specified point in time.

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

The following table describes the variables.

• Sample code

  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 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.

• Query and analysis result

  {
      "status": "success",
      "data": {
          "resultType": "vector",
          "result": [
              {
                  "metric": {
                      "__name__": "up",
                      "instance": "demo.promlabs.com:10001",
                      "job": "demo"
                  },
                  "value": [
                      1676700550.696,
                      "1"
                  ]
              },
              {
                  "metric": {
                      "__name__": "up",
                      "instance": "demo.promlabs.com:10000",
                      "job": "demo"
                  },
                  "value": [
                      1676700550.696,
                      "1"
                  ]
              }
          ]
      }
  }

Range Queries API

The Range Queries API operation is used to query metrics at multiple points in time within a specified time range.

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

The following table describes the variables.

• Sample code

  The following sample code provides an example on how to query the metrics from 2023-02-18 14:09:59 to 2023-02-18 14:16:39. The interval is 60 seconds.

  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.

• Query and analysis result

  {
    "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"
            ]
          ]
        }
      ]
    }
  }

Query Series API

The Query Series API operation is used to query all metric names and label-based numeric pairs that meet specified conditions within a specified period of time.

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

The following table describes the variables.

• Configuration example

  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.

• Query and analysis result

  {
      "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"
          }
      ]
  }

Query Label Names API

The Query Label Names API operation is used to query all label names that meet specified conditions within a specified period of time.

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

The following table describes the variables.

• Configuration example

  The following sample code provides an example on how to query the label names of all metrics within a specified period of time:

  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.

• Query and analysis result

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

Query Label Values API

The Query Label Values API operation is used to query all label values for specified label names that meet specified conditions within a specified period of time.

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

The following table describes the variables.

• Configuration example

  The following sample code provides an example on how to query all values of the instance label for the up metric within a specified period of time:

  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.

• Query and analysis result

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

Call a query API operation over HTTP

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)
	}
}

Call a query API operation by using an SDK for Prometheus

In this example, the version of the SDK for Prometheus that is used is v1.14.0. For more information, see 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)
}

Failed authentication

If the following information is returned, the authentication fails. We recommend that you specify a valid AccessKey pair.

{
    "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}"
}

Invalid PromQL statement

If the following information is returned, the PromQL statement is invalid. We recommend that you modify the query statement that is specified in the query parameter.

--> /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 error

If the following information is returned, the query times out. We recommend that you increase the value of the timeout parameter.

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

Incomplete query results

If the following information is returned, the query results are incomplete. We recommend that you narrow the query time range and perform the query again.

{
    "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"
    ]
}