DocsICP FilingConsole
Documentation
Home Page IoT Platform (Deprecated) User Guide Data services Data application Visualize IoT platform data with Prometheus

Visualize IoT platform data with Prometheus

Updated at:
Copy as MD
Product
My Favorites

Push device data from the IoT Platform, such as time-series data of Thing Model properties, data forwarded by time-series storage rules, and data from custom time-series storage tables, to Prometheus for storage and processing. Use this data for real-time monitoring, prediction, and fault diagnosis to improve device performance, reliability, and management efficiency.

Background

  • Prometheus is an open-source systems monitoring and alerting toolkit. The Prometheus UI provides built-in visualization. Visit the official Prometheus website for a detailed overview, documentation, tool downloads, and the latest release information. Use the documentation to learn how to monitor and alert with Prometheus, and how to integrate it with other tools and platforms.

  • IoT Platform provides a real-time monitoring feature that displays custom metrics. For more information, see Real-time monitoring user guide.

This topic describes how to use Prometheus to quickly ingest and visualize data from IoT Platform.

Scenarios

Use Prometheus to visualize and monitor device data from the IoT Platform in the following scenarios:

  • Device monitoring and fault detection

    Monitor the status and performance metrics of your IoT devices—such as temperature, humidity, and battery levels—to promptly detect, diagnose, and fix failures.

  • Resource management and optimization

    Improve resource utilization and system performance by monitoring key metrics, such as device energy consumption, network bandwidth, and storage space.

  • Data analysis and prediction

    Analyze and predict trends from the large volumes of data that your IoT devices generate to extract valuable insights for informed decision-making.

  • Security monitoring and threat detection

    Enhance the security of your IoT Platform by monitoring metrics in real time to detect potential vulnerabilities and attacks and trigger timely alarms.

  • Automated O&M

    Automate O&M for your IoT devices by integrating with automation tools and workflows. You can use monitoring data to trigger automatic actions, such as failure recovery and resource scale-out, thereby improving the reliability and scalability of your IoT Platform.

IoT Platform data for Prometheus

On your Prometheus server, use the following APIs from the IoT Platform cloud SDK to retrieve data.

Type

API

Related documentation

Time series data for TSL model properties

QueryDevicePropertyStatus

Use TSL models for device communication

Data from time series storage rules

QueryDevicesHotStorageDataStatus

Time series data storage overview

Data from custom time series storage tables

QueryCustomTimelineTableStatus

Custom time series storage table overview

Limitations

Only Enterprise Edition instances can send data to Prometheus for visualization, monitoring, and management.

How it works

image

Step 1: Install and start Prometheus Server

Before Prometheus can ingest data from the IoT platform, you must start the Prometheus Server. The following instructions use the prometheus-2.49.0-rc.0.windows-amd64.zip package for the Windows operating system as an example.

  1. Download the latest Prometheus package: prometheus-2.49.0-rc.0.windows-amd64.zip.

  2. Unzip the package, creating the prometheus-2.49.0-rc.0.windows-amd64 directory.

    The extracted directory contains the console_libraries and consoles directories, and the LICENSE, NOTICE, prometheus.exe, and prometheus.yml files.

  3. Open Command Prompt and navigate to the prometheus-2.49.0-rc.0.windows-amd64 directory.

  4. Run the following command to start Prometheus Server.

    prometheus.exe

  5. In your browser, open http://localhost:9090 to access the built-in Prometheus monitoring and management console.

    When the page loads, the Prometheus query interface appears. It includes an expression query input box, the Table and Graph tabs, and a data area displaying the message No data queried yet. This confirms that Prometheus Server started successfully.

Step 2: Integrate data with IoT and Prometheus SDKs

Alibaba Cloud provides SDKs for Java, Python, and Go. You can use these SDKs on your application server to develop an application that enables Prometheus to use IoT Platform as a data source for visual monitoring and management.

Step 1: Integrate device data via SDK

Java SDK

Environment configuration

Download and install the Java Development Kit (JDK) from the official Java website. Java 8 or later is required.

Maven project dependencies

  • Add the following Maven dependency for the IoT Platform cloud API:

    <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>iot20180120</artifactId>
    <version>5.0.0</version>
</dependency>

  • Add the following Maven dependencies for Prometheus:

    <dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient</artifactId>
    <version>0.9.0</version>
</dependency>
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient_httpserver</artifactId>
    <version>0.9.0</version>
</dependency>

SDK usage

  1. Retrieve device data by calling the data query APIs in the IoT Platform cloud SDK. For usage instructions, see Java SDK Usage Guide.

    2. QueryDevicePropertyStatus

    For the request and response parameters of this API, see QueryDevicePropertyStatus.

    import com.aliyun.iot20180120.models.QueryDevicePropertyStatusResponse;
import com.aliyun.tea.TeaException;
public class ApiUtil {
    public static com.aliyun.iot20180120.Client createClient(String accessKeyId,
                                                             String accessKeySecret,
                                                             String endpoint) throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setAccessKeyId(accessKeyId)
                .setAccessKeySecret(accessKeySecret);
        config.endpoint = endpoint;
        return new com.aliyun.iot20180120.Client(config);
    }
    public static String getSnapshotApi(String accessKeyId,
                                        String accessKeySecret,
                                        String endpoint,
                                        String iotInstanceId,
                                        String productKey,
                                        String deviceName) throws Exception {
        com.aliyun.iot20180120.Client client = api.createClient(accessKeyId, accessKeySecret, endpoint);
        com.aliyun.iot20180120.models.QueryDevicePropertyStatusRequest queryDevicePropertyStatusRequest = new com.aliyun.iot20180120.models.QueryDevicePropertyStatusRequest();
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            queryDevicePropertyStatusRequest.setIotInstanceId(iotInstanceId);
            queryDevicePropertyStatusRequest.setProductKey(productKey);
            queryDevicePropertyStatusRequest.setDeviceName(deviceName);
            QueryDevicePropertyStatusResponse queryDevicePropertyStatusResponse =
                    client.queryDevicePropertyStatusWithOptions(queryDevicePropertyStatusRequest, runtime);
            return queryDevicePropertyStatusResponse.getBody().getData().getList().getPropertyStatusInfo().get(0).getValue();
        } catch (TeaException error) {
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception error_e) {
            TeaException error = new TeaException(_error.getMessage(), error_e);
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
        return null;
    }
}

    QueryDevicesHotStorageDataStatus

    For the request and response parameters of this API, see QueryDevicesHotStorageDataStatus.

    import com.aliyun.iot20180120.models.QueryDevicesHotStorageDataStatusResponse;
import com.aliyun.tea.TeaException;
public class ApiUtil {
    public static com.aliyun.iot20180120.Client createClient(String accessKeyId,
                                                             String accessKeySecret,
                                                             String endpoint) throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setAccessKeyId(accessKeyId)
                .setAccessKeySecret(accessKeySecret);
        config.endpoint = endpoint;
        return new com.aliyun.iot20180120.Client(config);
    }
    public static String getSnapshotTopicApi(String accessKeyId,
                                             String accessKeySecret,
                                             String endpoint,
                                             String iotInstanceId,
                                             String productKey,
                                             String deviceName,
                                             Integer asc,
                                             Integer pageSize,
                                             String userTopic) throws Exception {
        com.aliyun.iot20180120.Client client = api.createClient(accessKeyId, accessKeySecret, endpoint);
        com.aliyun.iot20180120.models.QueryDevicesHotStorageDataStatusRequest queryDevicesHotStorageDataStatusRequest = new com.aliyun.iot20180120.models.QueryDevicesHotStorageDataStatusRequest();
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            queryDevicesHotStorageDataStatusRequest.setIotInstanceId(iotInstanceId);
            queryDevicesHotStorageDataStatusRequest.setProductKey(productKey);
            queryDevicesHotStorageDataStatusRequest.setDeviceName(deviceName);
            queryDevicesHotStorageDataStatusRequest.setAsc(asc);
            queryDevicesHotStorageDataStatusRequest.setPageSize(pageSize);
            queryDevicesHotStorageDataStatusRequest.setUserTopic(userTopic);
            QueryDevicesHotStorageDataStatusResponse queryDevicesHotStorageDataStatusResponse =
                    client.queryDevicesHotStorageDataStatusWithOptions(queryDevicesHotStorageDataStatusRequest, runtime);
            return queryDevicesHotStorageDataStatusResponse.getBody().getData().getList().getPropertyStatusDataInfo().get(0).getValue();
        } catch (TeaException error) {
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception error_e) {
            TeaException error = new TeaException(_error.getMessage(), error_e);
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
        return null;
    }
}

    QueryCustomTimelineTableStatus

    For the request and response parameters of this API, see QueryCustomTimelineTableStatus.

    import com.aliyun.iot20180120.models.QueryCustomTimelineTableStatusRequest;
import com.aliyun.iot20180120.models.QueryCustomTimelineTableStatusResponse;
import com.aliyun.tea.TeaException;
public class ApiUtil {
    public static com.aliyun.iot20180120.Client createClient(String accessKeyId,
                                                             String accessKeySecret,
                                                             String endpoint) throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setAccessKeyId(accessKeyId)
                .setAccessKeySecret(accessKeySecret);
        config.endpoint = endpoint;
        return new com.aliyun.iot20180120.Client(config);
    }
    public static String getCustomSnapshotApi(String accessKeyId,
                                              String accessKeySecret,
                                              String endpoint,
                                              String iotInstanceId,
                                              String tableName) throws Exception {
        com.aliyun.iot20180120.Client client = ApiUtil.createClient(accessKeyId, accessKeySecret, endpoint);
        com.aliyun.iot20180120.models.QueryCustomTimelineTableStatusRequest queryCustomTimelineTableStatusRequest = new QueryCustomTimelineTableStatusRequest();
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            queryCustomTimelineTableStatusRequest.setIotInstanceId(iotInstanceId);
            queryCustomTimelineTableStatusRequest.setTableName(tableName);
            QueryCustomTimelineTableStatusResponse queryCustomTimelineTableStatusResponse =
                    client.queryCustomTimelineTableStatusWithOptions(queryCustomTimelineTableStatusRequest, runtime);
            return queryCustomTimelineTableStatusResponse.getBody().getData().getResultJson();
        } catch (TeaException error) {
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception error_e) {
            TeaException error = new TeaException(error_e.getMessage(), error_e);
            System.out.println(error.getMessage());
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
        return null;
    }
}

  2. Use the Prometheus SDK to read the IoT Platform data source.

    1. Call the HTTPServer() method to configure the Prometheus Server endpoint port. The sample code sets this port to 8084.

      new HTTPServer(8084);

    2. Call the Gauge.build("name","help").register() method to register a Gauge object and define a metric identifier to store the data.

      The name parameter is the metric identifier, such as testJavaSnapshotRaw or testJavaSnapshotTopic. The help parameter is a description, such as test num. You can then use the name to view and analyze the corresponding metric data in the Prometheus monitoring dashboard.

      You can register multiple Gauge objects to store data for different metrics.

              Gauge gaugeRaw = Gauge.build("testJavaSnapshotRaw", "test num").register();
        Gauge gaugeTopic = Gauge.build("testJavaSnapshotTopic", "test num").register();
        Gauge gaugeCustom =  Gauge.build("testCustomTableSnapshot", "test num").register();

    3. Call the set() method of the Gauge object to set the metric's value to the value of a specific field from the IoT Platform cloud API response.

              while (true) {
            String resultRaw = ApiUtil.getSnapshotApi(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID_LP"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET_LP"),
                    "yourEndpoint", "yourIotInstanceId", "yourProductKey", "yourDeviceName");
            gaugeRaw.set(Double.parseDouble(Objects.requireNonNull(resultRaw)));
            String resultTopic = ApiUtil.getSnapshotTopicApi("yourAccessKey", "yourAccessSecret",
                    "yourEndpoint", "yourIotInstanceId", "yourProductKey", "yourDeviceName", 0, 1,"yourTopic");
            gaugeTopic.set(Double.parseDouble(Objects.requireNonNull(resultTopic)));
            String resultJson = ApiUtil.getCustomSnapshotApi("yourAccessKey", "yourAccessSecret",
                    "yourEndpoint", "yourIotInstanceId", "yourtableName");
            List<Map<String, Object>> resultList = (List<Map<String, Object>>) JSONArray.parse(resultJson);
            gaugeCustom.set(Double.parseDouble(Objects.requireNonNull(resultList).get(0).get("avg_humidity").toString()));
            Thread.sleep(3000);
        }

      In a real-world scenario, replace the following placeholder parameters with your actual values:

      Parameter

      Description

      yourAccessKey

      The AccessKey ID and AccessKey Secret of your Alibaba Cloud account or a RAM user.

      Log on to the IoT Platform console, hover over your profile picture, and then click AccessKey Management to obtain the AccessKey ID and AccessKey Secret.

      Important

      To avoid security risks, do not hard-code your AccessKey in your code. Use environment variables to manage your AccessKey instead.

      Add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables on your local system, and set them to your AccessKey ID and AccessKey Secret, respectively.

      Retrieve them in your code as follows:

      • System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")

      • System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

      yourAccessSecret

      yourEndpoint

      The endpoint for calling the cloud service. The format for IoT Platform endpoints is iot.${RegionId}.aliyuncs.com. Replace the variable ${RegionId} with the region ID for your IoT Platform service. For Alibaba Cloud region IDs, see Supported regions.

      yourIotInstanceId

      The instance ID. You can find the ID of the instance on the Instance Overview page on the IoT Platform console.

      yourProductKey

      The ProductKey of the product and the name of the device. You can find this information on the device details page. For instructions, see View device information.

      yourDeviceName

      yourTopic

      When calling the QueryDevicesHotStorageDataStatus API, pass the custom topic for the data you want to query. Enter all topic levels that come after the user level.

      For example: user/a***/b***. For more information about custom topics, see Use custom topics for communication.

      yourtableName

      When calling the QueryCustomTimelineTableStatus API, pass the table identifier of the custom time series storage table that contains the data to query.

      To find the table identifier, see View information about a custom storage table.

Complete sample code

For the complete sample code, see Prometheus Java SDK demo.

Python SDK

Environment setup

  1. Visit the official Python website to download and install Python. The SDK requires Python 3.7 or later.

  2. Visit the official pip website to download and install pip. You can skip this step if you already have pip.

Dependencies

  • Install the SDK package for the Alibaba Cloud IoT Platform cloud API:

    pip install alibabacloud_iot20180120

  • Install the required package for Prometheus:

    pip install prometheus_client

SDK usage

  1. Use the Alibaba Cloud IoT Platform SDK to call data query APIs and retrieve device data. For usage instructions, see Python SDK Usage Guide.

    2. QueryDevicePropertyStatus

    For details on request and response parameters, see QueryDevicePropertyStatus.

    from alibabacloud_iot20180120.client import Client as Iot20180120Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_iot20180120 import models as iot_20180120_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient
def create_client(access_key_id, access_key_secret, endpoint):
    config = open_api_models.Config(access_key_id=access_key_id, access_key_secret=access_key_secret)
    config.endpoint = endpoint
    return Iot20180120Client(config)
def get_snapshot_api(access_key_id, access_key_secret, endpoint, iot_instance_id, product_key, device_name):
    client = create_client(access_key_id=access_key_id, access_key_secret=access_key_secret, endpoint=endpoint)
    query_device_property_status_request = iot_20180120_models.QueryDevicePropertyStatusRequest()
    query_device_property_status_request.iot_instance_id = iot_instance_id
    query_device_property_status_request.product_key = product_key
    query_device_property_status_request.device_name = device_name
    runtime = util_models.RuntimeOptions()
    try:
        return client.query_device_property_status_with_options(query_device_property_status_request, runtime)
    except Exception as error:
        UtilClient.assert_as_string(error.message)

    QueryDevicesHotStorageDataStatus

    For details on request and response parameters, see QueryDevicesHotStorageDataStatus.

    from alibabacloud_iot20180120.client import Client as Iot20180120Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_iot20180120 import models as iot_20180120_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient
def create_client(access_key_id, access_key_secret, endpoint):
    config = open_api_models.Config(access_key_id=access_key_id, access_key_secret=access_key_secret)
    config.endpoint = endpoint
    return Iot20180120Client(config)
def get_snapshot_topic_api(access_key_id, access_key_secret, endpoint, iot_instance_id, product_key, device_name, asc, page_size, user_topic):
    client = create_client(access_key_id=access_key_id, access_key_secret=access_key_secret, endpoint=endpoint)
    query_devices_hot_storage_data_status_request = iot_20180120_models.QueryDevicesHotStorageDataStatusRequest()
    query_devices_hot_storage_data_status_request.iot_instance_id = iot_instance_id
    query_devices_hot_storage_data_status_request.product_key = product_key
    query_devices_hot_storage_data_status_request.device_name = device_name
    query_devices_hot_storage_data_status_request.asc = asc
    query_devices_hot_storage_data_status_request.page_size = page_size
    query_devices_hot_storage_data_status_request.user_topic = user_topic
    runtime = util_models.RuntimeOptions()
    try:
        return client.query_devices_hot_storage_data_status_with_options(query_devices_hot_storage_data_status_request, runtime)
    except Exception as error:
        UtilClient.assert_as_string(error.message)

    QueryCustomTimelineTableStatus

    For details on request and response parameters, see QueryCustomTimelineTableStatus.

    from alibabacloud_iot20180120.client import Client as Iot20180120Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_iot20180120 import models as iot_20180120_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient
def create_client(access_key_id, access_key_secret, endpoint):
    config = open_api_models.Config(access_key_id=access_key_id, access_key_secret=access_key_secret)
    config.endpoint = endpoint
    return Iot20180120Client(config)
def get_custom_snapshot_api(access_key_id, access_key_secret, endpoint, iot_instance_id, table_name):
    client = create_client(access_key_id=access_key_id, access_key_secret=access_key_secret, endpoint=endpoint)
    query_custom_timeline_table_status_request = iot_20180120_models.QueryCustomTimelineTableStatusRequest()
    query_custom_timeline_table_status_request.iot_instance_id = iot_instance_id
    query_custom_timeline_table_status_request.table_name = table_name
    runtime = util_models.RuntimeOptions()
    try:
        return client.query_custom_timeline_table_status_with_options(query_custom_timeline_table_status_request, runtime)
    except Exception as error:
        UtilClient.assert_as_string(error.message)

  2. Use the Prometheus SDK to read data from the Alibaba Cloud IoT Platform data source.

    1. Call the start_http_server() method to configure the port from which the Prometheus server scrapes data. The sample code sets it to 8083.

      start_http_server(8083)

    2. Call the Gauge("name","help") method to register a Gauge metric object and define a metric identifier to store the data.

      The name parameter is the metric identifier, such as testPythonSnapshotRaw or testPythonSnapshotTopic. The help parameter provides a description for the metric, such as test sample. You can then use the name to view and analyze the corresponding metric data in the Prometheus monitoring dashboard.

      You can register multiple Gauge objects to store data for different metrics.

      g_raw = Gauge('testPythonSnapshotRaw', 'test sample')
g_topic = Gauge('testPythonSnapshotTopic', 'test sample')
g_custom = Gauge('testPythonCustomSnapshot', 'test sample')

    3. Call the set() method of the Gauge object to assign a value from a specific field in the Alibaba Cloud IoT Platform cloud API response.

      while True:
    result_raw = api.get_snapshot_api(access_key_id="", access_key_secret="",
                                      endpoint="", iot_instance_id="",
                                      product_key="", device_name="")
    g_raw.set(result_raw.body.data.list.property_status_info[0].value)
    result_topic = api.get_snapshot_topic_api(access_key_id="", access_key_secret="",
                                              endpoint="", iot_instance_id="",
                                              product_key="", device_name="", asc="0",
                                              page_size="1", user_topic="")
    g_topic.set(result_topic.body.data.list.property_status_data_info[0].value)
    result_json = api.get_custom_snapshot_api(access_key_id="", access_key_secret="",
                                          endpoint="", iot_instance_id="",
                                          table_name="")
    result_custom = json.loads(result_json.body.data.result_json)  
    for row in result_custom:
        g_custom.set(row["avg_humidity"])
    time.sleep(3)

      Replace the following placeholder parameters with your actual values:

      Parameter

      Description

      access_key_id

      The AccessKey ID and AccessKey Secret of your Alibaba Cloud account or a RAM user.

      Log on to the Alibaba Cloud IoT Platform console, move your pointer over your profile picture, and then click AccessKey Management to obtain your AccessKey ID and AccessKey Secret.

      Important

      To avoid security risks from hard-coding your AccessKey into business code, use environment variables to manage it.

      Add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to your operating system and set them to your AccessKey ID and AccessKey Secret, respectively.

      You can retrieve them in the sample code by using the following methods:

      • os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID")

      • os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

      access_key_secret

      endpoint

      The endpoint for the Alibaba Cloud IoT Platform cloud API. The format for Alibaba Cloud IoT Platform endpoints is iot.${RegionId}.aliyuncs.com. Replace the ${RegionId} variable with the region ID for your IoT Platform service. For Alibaba Cloud region IDs, see Supported regions.

      iot_instance_id

      The instance ID. You can find this ID on the Instance Overview page in the Alibaba Cloud IoT Platform console.

      product_key

      The ProductKey and name of the target device. You can find this information on the device details page. For instructions, see View device information.

      device_name

      user_topic

      When calling the QueryDevicesHotStorageDataStatus API, specify the custom topic to query. This value must include all topic levels that follow the user prefix.

      For example: user/a***/b***. For more information about custom topics, see Use custom topics for communication.

      table_name

      When calling the QueryCustomTimelineTableStatus API, specify the identifier of the custom time series storage table to query.

      To find the table identifier, see View information about a custom storage table.

Complete sample code

For a complete example of how to use the Alibaba Cloud IoT Platform SDK and the Prometheus SDK together, see Prometheus Python SDK demo.

Go SDK

Environment setup

  1. Visit the Go official website to install the Go development environment. Go 1.13.0 or later is required.

  2. After Go is installed, create the GOPATH environment variable and set its value to your code directory.

    To learn more about GOPATH, run go help gopath.

Dependencies

  • The Alibaba Cloud IoT Platform cloud-side API requires the following packages:

    go get github.com/alibabacloud-go/tea/tea
go get github.com/alibabacloud-go/darabonba-openapi/v2/client
go get github.com/alibabacloud-go/iot-20180120/v6/client
go get github.com/alibabacloud-go/tea-utils/v2/service

  • Prometheus requires the following packages:

    go get github.com/prometheus/client_golang/prometheus
go get github.com/prometheus/client_golang/prometheus/promhttp

SDK usage

  1. Use the Alibaba Cloud IoT Platform cloud-side SDK to retrieve device data by calling data query APIs. For instructions, see Go SDK Instructions.

    2. QueryDevicePropertyStatus

    See QueryDevicePropertyStatus for this API's request and response parameters.

    import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	iot20180120 "github.com/alibabacloud-go/iot-20180120/v6/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
)
func CreateClient(accessKeyId *string, accessKeySecret *string, endpoint *string) (_result *iot20180120.Client, _err error) {
	config := &openapi.Config{
		// Required. Your AccessKey ID.
		AccessKeyId: accessKeyId,
		// Required. Your AccessKey Secret.
		AccessKeySecret: accessKeySecret,
	}
	// For more information about endpoints, see https://api.aliyun.com/product/Iot.
	// config.Endpoint = tea.String("iot.cn-shanghai.aliyuncs.com")
	config.Endpoint = endpoint
	_result = &iot20180120.Client{}
	_result, _err = iot20180120.NewClient(config)
	return _result, _err
}
func getSnapshotApi(accessKeyId *string, accessKeySecret *string, endpoint *string, iotInstanceId *string, productKey *string,
	deviceName *string) (queryDevicePropertyStatusResponse *iot20180120.QueryDevicePropertyStatusResponse, _err error) {
	client, _err := CreateClient(accessKeyId, accessKeySecret, endpoint)
	if _err != nil {
		return nil, _err
	}
	queryDevicePropertyStatusRequest := &iot20180120.QueryDevicePropertyStatusRequest{}
	queryDevicePropertyStatusRequest.IotInstanceId = iotInstanceId
	queryDevicePropertyStatusRequest.ProductKey = productKey
	queryDevicePropertyStatusRequest.DeviceName = deviceName
	queryDevicePropertyStatusResponse = &iot20180120.QueryDevicePropertyStatusResponse{}
	runtime := &util.RuntimeOptions{}
	tryErr := func() (_e error) {
		defer func() {
			if r := tea.Recover(recover()); r != nil {
				_e = r
			}
		}()
		queryDevicePropertyStatusResponse, _err = client.QueryDevicePropertyStatusWithOptions(queryDevicePropertyStatusRequest, runtime)
		if _err != nil {
			return _err
		}
		return nil
	}()
	if tryErr != nil {
		var error = &tea.SDKError{}
		if _t, ok := tryErr.(*tea.SDKError); ok {
			error = _t
		} else {
			error.Message = tea.String(tryErr.Error())
		}
		// If necessary, print the error.
		_, _err = util.AssertAsString(error.Message)
		if _err != nil {
			return queryDevicePropertyStatusResponse, _err
		}
	}
	return queryDevicePropertyStatusResponse, _err
}

    QueryDevicesHotStorageDataStatus

    See QueryDevicesHotStorageDataStatus for this API's request and response parameters.

    import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	iot20180120 "github.com/alibabacloud-go/iot-20180120/v6/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
)
func CreateClient(accessKeyId *string, accessKeySecret *string, endpoint *string) (_result *iot20180120.Client, _err error) {
	config := &openapi.Config{
		// Required. Your AccessKey ID.
		AccessKeyId: accessKeyId,
		// Required. Your AccessKey Secret.
		AccessKeySecret: accessKeySecret,
	}
	// For more information about endpoints, see https://api.aliyun.com/product/Iot.
	// config.Endpoint = tea.String("iot.cn-shanghai.aliyuncs.com")
	config.Endpoint = endpoint
	_result = &iot20180120.Client{}
	_result, _err = iot20180120.NewClient(config)
	return _result, _err
}
func getSnapshotTopicApi(accessKeyId *string, accessKeySecret *string, endpoint *string, iotInstanceId *string, productKey *string,
	deviceName *string, asc *int32, pageSize *int32, userTopic *string) (queryDevicesHotStorageDataStatusResponse *iot20180120.QueryDevicesHotStorageDataStatusResponse, _err error) {
	client, _err := CreateClient(accessKeyId, accessKeySecret, endpoint)
	if _err != nil {
		return nil, _err
	}
	queryDevicesHotStorageDataStatusRequest := &iot20180120.QueryDevicesHotStorageDataStatusRequest{}
	queryDevicesHotStorageDataStatusRequest.IotInstanceId = iotInstanceId
	queryDevicesHotStorageDataStatusRequest.ProductKey = productKey
	queryDevicesHotStorageDataStatusRequest.DeviceName = deviceName
	queryDevicesHotStorageDataStatusRequest.Asc = asc
	queryDevicesHotStorageDataStatusRequest.PageSize = pageSize
	queryDevicesHotStorageDataStatusRequest.UserTopic = userTopic
	queryDevicesHotStorageDataStatusResponse = &iot20180120.QueryDevicesHotStorageDataStatusResponse{}
	runtime := &util.RuntimeOptions{}
	tryErr := func() (_e error) {
		defer func() {
			if r := tea.Recover(recover()); r != nil {
				_e = r
			}
		}()
		queryDevicesHotStorageDataStatusResponse, _err = client.QueryDevicesHotStorageDataStatusWithOptions(queryDevicesHotStorageDataStatusRequest, runtime)
		if _err != nil {
			return _err
		}
		return nil
	}()
	if tryErr != nil {
		var error = &tea.SDKError{}
		if _t, ok := tryErr.(*tea.SDKError); ok {
			error = _t
		} else {
			error.Message = tea.String(tryErr.Error())
		}
		// If necessary, print the error.
		_, _err = util.AssertAsString(error.Message)
		if _err != nil {
			return queryDevicesHotStorageDataStatusResponse, _err
		}
	}
	return queryDevicesHotStorageDataStatusResponse, _err
}

    QueryCustomTimelineTableStatus

    See QueryCustomTimelineTableStatus for this API's request and response parameters.

    import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	iot20180120 "github.com/alibabacloud-go/iot-20180120/v6/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
)
func CreateClient(accessKeyId *string, accessKeySecret *string, endpoint *string) (_result *iot20180120.Client, _err error) {
	config := &openapi.Config{
		// Required. Your AccessKey ID.
		AccessKeyId: accessKeyId,
		// Required. Your AccessKey Secret.
		AccessKeySecret: accessKeySecret,
	}
	// For more information about endpoints, see https://api.aliyun.com/product/Iot.
	// config.Endpoint = tea.String("iot.cn-shanghai.aliyuncs.com")
	config.Endpoint = endpoint
	_result = &iot20180120.Client{}
	_result, _err = iot20180120.NewClient(config)
	return _result, _err
}
func getCustomSnapshotApi(accessKeyId *string, accessKeySecret *string, endpoint *string, iotInstanceId *string,
	tableName *string) (queryCustomTimelineTableStatusResponse *iot20180120.QueryCustomTimelineTableStatusResponse, _err error) {
	client, _err := CreateClient(accessKeyId, accessKeySecret, endpoint)
	if _err != nil {
		return nil, _err
	}
	queryCustomTimelineTableStatusRequest := &iot20180120.QueryCustomTimelineTableStatusRequest{}
	queryCustomTimelineTableStatusRequest.IotInstanceId = iotInstanceId
	queryCustomTimelineTableStatusRequest.TableName = tableName
	queryCustomTimelineTableStatusResponse = &iot20180120.QueryCustomTimelineTableStatusResponse{}
	runtime := &util.RuntimeOptions{}
	tryErr := func() (_e error) {
		defer func() {
			if r := tea.Recover(recover()); r != nil {
				_e = r
			}
		}()
		queryCustomTimelineTableStatusResponse, _err = client.QueryCustomTimelineTableStatusWithOptions(queryCustomTimelineTableStatusRequest, runtime)
		if _err != nil {
			return _err
		}
		return nil
	}()
	if tryErr != nil {
		var error = &tea.SDKError{}
		if _t, ok := tryErr.(*tea.SDKError); ok {
			error = _t
		} else {
			error.Message = tea.String(tryErr.Error())
		}
		// If necessary, print the error.
		_, _err = util.AssertAsString(error.Message)
		if _err != nil {
			return queryCustomTimelineTableStatusResponse, _err
		}
	}
	return queryCustomTimelineTableStatusResponse, _err
}

  2. Use the Prometheus SDK to read data from the Alibaba Cloud IoT Platform data source.

    1. Call the http.ListenAndServe() method to configure and start a web server on a port from which Prometheus can scrape data.

      	// Create an HTTP handler to expose metrics.
	http.Handle("/metrics", promhttp.Handler())
	// Start the web server.
	http.ListenAndServe(":8082", nil)

    2. Call the prometheus.NewGauge() method to create a Gauge metric object.

      The name parameter specifies the metric's name, such as GolangRaw or GolangTopic. The help parameter provides a description, such as test value. You can then use the specified name to view and analyze the metric in the Prometheus monitoring dashboard.

      var (
	// Create a Gauge metric.
	guageRaw = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "GolangRaw", // Metric name
		Help: "test value", // Help text for the metric
	})
)
var (
	guageTopic = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "GolangTopic", // Metric name
		Help: "test value", // Help text for the metric
	})
)
var (
	guageCustom = prometheus.NewGauge(prometheus.GaugeOpts{
		Name: "GolangCustom", // Metric name
		Help: "test value",   // Help text for the metric
	})
)

    3. Call the prometheus.MustRegister() method to register the Gauge metric objects that you created.

      	// Register the metrics.
	prometheus.MustRegister(guageRaw)
	prometheus.MustRegister(guageTopic)
prometheus.MustRegister(guageCustom)

      You can create and register multiple Gauge metric objects to receive and store data for different metrics.

    4. Call the set() method on a Gauge object to set its value to a value returned by an Alibaba Cloud IoT Platform cloud-side API.

      QueryDevicePropertyStatus

      func testRaw() {
	go func() {
		for {
			queryDevicePropertyStatusResponse, _err := getSnapshotApi(tea.String("accessKeyId"), tea.String("accessKeySecret"),
				tea.String("endpoint"), tea.String("iotInstanceId"), tea.String("productKey"), tea.String("deviceName"))
			queryDevicePropertyStatusResponseBodyDataListPropertyStatusInfo := queryDevicePropertyStatusResponse.Body.Data.List.PropertyStatusInfo
			var value *string = queryDevicePropertyStatusResponseBodyDataListPropertyStatusInfo[0].Value
			var floatValue float64
			floatValue, _ = strconv.ParseFloat(*value, 64)
			if _err != nil {
				panic(_err)
			}
			guageRaw.Set(floatValue)
			time.Sleep(3 * time.Second)
		}
	}()
}

      QueryDevicesHotStorageDataStatus

      func testTopic() {
	go func() {
		var asc int32 = 0
		var pageSize int32 = 1
		for {
      queryDevicesHotStorageDataStatusResponse, _err := getSnapshotTopicApi(tea.String("accessKeyId"), tea.String("accessKeySecret"),
				tea.String("endpoint"), tea.String("iotInstanceId"), tea.String("productKey"), tea.String("deviceName"),
                                                                            &asc, &pageSize, tea.String("userTopic"))
			queryDevicesHotStorageDataStatusResponseBodyDataListPropertyStatusDataInfo := queryDevicesHotStorageDataStatusResponse.Body.Data.List.PropertyStatusDataInfo
			var value *string = queryDevicesHotStorageDataStatusResponseBodyDataListPropertyStatusDataInfo[0].Value
			var floatValue float64
			floatValue, _ = strconv.ParseFloat(*value, 64)
			if _err != nil {
				panic(_err)
			}
			guageTopic.Set(floatValue)
			time.Sleep(3 * time.Second)
		}
	}()
}

      QueryCustomTimelineTableStatus

      func testCustom() {
	go func() {
		for {
			queryCustomTimelineTableStatusResponse, _err := getCustomSnapshotApi(tea.String("accessKeyId"), tea.String("accessKeySecret"),
				tea.String("endpoint"), tea.String("iotInstanceId"), tea.String("tableName"))
			var config []map[string]interface{}
			err := json.Unmarshal([]byte(*queryCustomTimelineTableStatusResponse.Body.Data.ResultJson), &config)
			if err != nil {
				panic(err)
			}
			if _err != nil {
				panic(_err)
			}
			guageCustom.Set(config[0]["avg_humidity"].(float64))
			time.Sleep(3 * time.Second)
		}
	}()
}

      Replace the following placeholder parameters with your actual values:

      Parameter

      Description

      accessKeyId

      The AccessKey ID and AccessKey Secret of your Alibaba Cloud account or a RAM user.

      Log in to the IoT Platform console, hover over your profile picture, and then click AccessKey Management to get your AccessKey ID and AccessKey Secret.

      Important

      To avoid security risks, do not hard-code your AccessKeys into your business logic. We recommend that you use environment variables to manage your AccessKeys.

      Add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to your local operating system and set them to your AccessKey ID and AccessKey Secret, respectively.

      In the sample code, you can retrieve these values by calling:

      • os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")

      • os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

      accessKeySecret

      endpoint

      The endpoint for calling the cloud service. The endpoint format for Alibaba Cloud IoT Platform is iot.${RegionId}.aliyuncs.com. Replace the ${RegionId} variable with the Region ID of your IoT Platform service. For a list of Alibaba Cloud Region IDs, see Supported Regions.

      iotInstanceId

      The Instance ID. You can find the ID of your current instance on the Instance Overview page on the IoT Platform console.

      productKey

      The ProductKey and DeviceName of the device. You can find this information on the device details page. For instructions, see View device information.

      deviceName

      userTopic

      When calling the QueryDevicesHotStorageDataStatus API, specify the desired custom topic by entering all topic levels that follow the user level.

      Example: user/a***/b***. For more information about custom topics, see Use Custom Topics for Communication.

      tableName

      When calling the QueryCustomTimelineTableStatus API, specify the table identifier of the custom time series table that you want to query.

      To find the table identifier, see View custom storage table information.

Complete sample code

See Prometheus Go SDK demo for a complete example of using the Alibaba Cloud IoT Platform cloud-side SDK with the Prometheus SDK.

Step 2: Run the SDK demo

Important

Before you run the demo, replace the relevant parameters with your actual values.

After you run the demo, go to http://localhost:8084/metrics in a browser to view the data retrieved by the Prometheus SDK. The Prometheus Server can then scrape the IoT Platform data source from http://localhost:8084/metrics.

Note

8084 is an example value. This is the access port you configure when using the Prometheus SDK to retrieve data from the IoT Platform.

For example, a device reports the following thing model property data:

{
	"id": 1703*****418,
	"params": {
		"cpu_temperature": 60,
		"cpu_usage": 1.3
	},
	"version": "1.0",
	"method": "thing.event.property.post"
}

The following shows the data for a property retrieved by the Prometheus SDK:

# HELP testJavaSnapshotRaw test num
# TYPE testJavaSnapshotRaw gauge
testJavaSnapshotRaw 60.0

Step 3: Configure and start Prometheus to scrape data

After starting the Prometheus server and running the SDK demo program, Prometheus cannot yet retrieve any data. Configure the prometheus.yml file to have the Prometheus server periodically scrape the IoT platform data source exposed by the SDK demo program.

  1. Open prometheus.yml in the prometheus-2.49.0.windows-amd64 directory.

  2. Under the global and scrape_configs sections, configure the scrape interval, add a new job to scrape data, and save the file.

    • prometheus (default job): Scrapes data from http://localhost:9090/.

    • testjava: A job that you add. You can customize the job name. This job scrapes data from http://localhost:8084/metrics. Note that 8084 is an example; use the access port you configured in Step 2.

      • global:
  scrape_interval: 5s
........
scrape_configs:
  - job_name: "prometheus"
    static_configs:
    - targets: ["localhost:9090"]
  - job_name: 'testjava'
    static_configs:
    - targets: ['localhost:8084']

  3. Restart the Prometheus server. For instructions, see Step 1.

  4. In the built-in Prometheus monitoring and management console, enter the expression up and click Execute.

    A value of 1 indicates that a target is healthy.

    The value for both the up{instance="localhost:8084", job="testjava"} and up{instance="localhost:9090", job="prometheus"} instances is 1.

Step 4: View data in the Prometheus Graph

After Prometheus scrapes the data, you can view it in the built-in monitoring console.

  1. In the Prometheus monitoring console, click the Graph tab.

  2. Enter the field identifier for the gauge metric, such as testJavaSnapshotRaw, and then click Execute.

    By default, the console displays the time series data for this metric from the last hour.

For more on monitoring and managing data with Prometheus, see the official Prometheus documentation.

Previous：Connector for real-time data integrationNext：Maintenance