Enable Monitoring for Dify LLM Apps at Scale via API - ARMS

The Dify console lets you configure monitoring for each application and integrate it with Cloud Monitor for observability. However, the console does not support batch configuration. This topic describes how to call APIs to batch-configure Alibaba Cloud observability monitoring for Dify applications.

Background

The overall process simulates Dify console operations using HTTP APIs to perform the batch configuration:

Obtain logon status: Call the logon API to obtain an authentication token.
Retrieve the application list: Retrieve information about all applications that belong to the tenant.
Check the application monitoring configuration: Query the current monitoring configuration status of the application.
Configure Alibaba Cloud monitoring: Create an Alibaba Cloud observability configuration for the application.
Enable the monitoring switch: Turn on application monitoring.

If you perform custom development by deploying Dify from the source code, you can also implement batch configuration. To do so, follow the process described above and use the existing O&M commands in Dify's ext_commands.py file with Click Command.

API batch configuration flow

Step 1: Log on and authenticate

Call the Dify logon API to perform identity authentication and obtain the tenant's logon token.

API: POST {base_url}/console/api/login

Request parameters

{
  "email": "your_account@example.com",
  "password": "your_password",
  "remember_me": false
}

Response

{
  "result": "success"
}

Set-Cookie: access_token=<JWT>; HttpOnly; Max-Age=3600
Set-Cookie: refresh_token=<random>; HttpOnly; Max-Age=2592000
Set-Cookie: csrf_token=<JWT>; Max-Age=3600

Key information in the response

Cookie	Purpose
`access_token`	API authentication credential
`refresh_token`	Credential to renew the access_token
`csrf_token`	Cross-Site Request Forgery (CSRF) credential

Subsequent requests

In the request header, set:

Cookie: access_token=xxx; refresh_token=xxx; csrf_token=xxx
X-CSRF-Token: <csrf_token>

Note

If you use a library that has session features, the library usually manages cookies automatically. In this case, you only need to add X-CSRF-Token to the header.

Step 2: Get the application list

Retrieve information for all applications that belong to the current tenant.

API: GET {base_url}/console/api/apps

Request parameters

Parameter	Type	Default value	Description
`page`	int	1	The page number. Starts from 1.
`limit`	int	20	The number of items per page. Valid values: 1 to 100.
`mode`	string	"all"	Filter by application type.
`name`	string	-	Search by application name.

Paging instructions:

Use the returned has_more field to determine whether a next page exists.
To retrieve all applications, loop the requests until the has_more field in the response is false.

Response

{
  "page": 1,
  "limit": 20,
  "total": 100,
  "has_more": true,
  "data": [
    {
      "id": "app-uuid",
      "name": "Application Name",
      "mode": "workflow",
      "description": "Application Description",
      "icon": "",
      "icon_type": "emoji",
      "created_at": 1234567890,
      "updated_at": 1234567890,
      "model_config": { /* Model Configuration */ },
      "workflow": { /* workflow configuration */ },
      "tags": []
    }
  ]
}

Key field descriptions:

id: The application ID. This is required for subsequent monitoring configuration steps.
name: The application name. This is required for the app_name parameter when you configure monitoring.

Step 3: Check the application monitoring configuration

Retrieve the current monitoring configuration status for the specified application. You can proceed to the next steps only if monitoring is not configured.

API: GET {base_url}/console/api/apps/{app_id}/trace

Request parameters

app_id: The application ID. You can obtain this ID in Step 2: Retrieve the application list.

Response

{
  "enabled": false,
  "tracing_provider": null
}

{
  "enabled": true,
  "tracing_provider": "aliyun"
}

Field descriptions:

enabled: Indicates whether monitoring is enabled (boolean).
tracing_provider: The name of the monitoring provider (string).

Step 4: Configure Alibaba Cloud monitoring

Create an Alibaba Cloud observability monitoring configuration for the application.

API: POST {base_url}/console/api/apps/{app_id}/trace-config

Request parameters

{
  "tracing_provider": "aliyun",
  "tracing_config": {
    "app_name": "xxx",
    "license_key": "your_aliyun_license_key",
    "endpoint": "http://tracing-analysis-dc-bj.aliyuncs.com"
  }
}

Field descriptions

Field	Description
`tracing_provider`	Fixed as `"aliyun"`
`tracing_config.app_name`	The Alibaba Cloud application name. When configuring in batches, do not use the same name. Identical names are treated as the same observability application. You can use the format `Dify workspace name`-`Dify application name`.
`tracing_config.license_key`	The Alibaba Cloud License Key. For more information, see DescribeTraceLicenseKey - List LicenseKey.
`tracing_config.endpoint`	The Alibaba Cloud reporting endpoint. For more information, see Endpoints.

Response

{
  "result": "success"
}

Note

In some versions of Dify, if you create an application configuration but do not enable it, the monitoring metrics in the console may appear abnormal. The metrics are displayed as normal after you enable the monitoring switch.

Step 5: Enable the monitoring switch

After you configure monitoring, you must enable the monitoring switch for the settings to take effect.

API: POST {base_url}/console/api/apps/{app_id}/trace

Request parameters

{
  "enabled": true,
  "tracing_provider": "aliyun"
}

Field	Type	Description
`enabled`	boolean	Specifies whether to enable monitoring (true/false).
`tracing_provider`	string	The name of the monitoring provider (aliyun).

Response

{
  "result": "success"
}