From 44b13023228dc5986c6bb21fedef4e22dd92446b Mon Sep 17 00:00:00 2001 From: -LAN- Date: Wed, 4 Nov 2026 21:44:17 +0800 Subject: [PATCH 1/2] docs: update self-host tracing integration guides Align the seven self-host monitoring integration guides with the unified ops tracing implementation at Dify 0fe1b06d1ea096bde2bba619a4cc1973bea9cdd2. Replace obsolete field inventories with current provider configuration, endpoint requirements, saved-credential behavior, Agent capture scope and inheritance, trace delivery guidance, and troubleshooting. Update the English, Chinese, and Japanese versions together. --- .../monitor/integrations/integrate-aliyun.mdx | 411 ++--------- .../monitor/integrations/integrate-arize.mdx | 584 ++------------- .../integrations/integrate-langfuse.mdx | 659 ++--------------- .../integrations/integrate-langsmith.mdx | 663 ++---------------- .../monitor/integrations/integrate-opik.mdx | 602 ++-------------- .../integrations/integrate-phoenix.mdx | 631 ++--------------- .../monitor/integrations/integrate-weave.mdx | 362 ++-------- .../monitor/integrations/integrate-aliyun.mdx | 411 ++--------- .../monitor/integrations/integrate-arize.mdx | 535 ++------------ .../integrations/integrate-langfuse.mdx | 659 ++--------------- .../integrations/integrate-langsmith.mdx | 383 ++-------- .../monitor/integrations/integrate-opik.mdx | 553 ++------------- .../integrations/integrate-phoenix.mdx | 582 ++------------- .../monitor/integrations/integrate-weave.mdx | 364 ++-------- .../monitor/integrations/integrate-aliyun.mdx | 251 ++----- .../monitor/integrations/integrate-arize.mdx | 345 ++------- .../integrations/integrate-langfuse.mdx | 659 ++--------------- .../integrations/integrate-langsmith.mdx | 403 ++--------- .../monitor/integrations/integrate-opik.mdx | 361 ++-------- .../integrations/integrate-phoenix.mdx | 394 ++--------- .../monitor/integrations/integrate-weave.mdx | 365 ++-------- 21 files changed, 971 insertions(+), 9206 deletions(-) diff --git a/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index ba493d751..7a5d4b86b 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -1,393 +1,80 @@ --- title: Integrate with Alibaba Cloud Monitor sidebarTitle: Alibaba Cloud Monitor -description: Send traces and metrics from Dify applications to Alibaba Cloud Monitor (ARMS) via OpenTelemetry +description: Send traces from Dify applications to Alibaba Cloud Monitor (ARMS) via OpenTelemetry --- -## What is Alibaba Cloud Monitor +## Connect Your App -Alibaba Cloud provides a fully managed, maintenance-free observability platform that enables one-click monitoring, tracing, and evaluation of Dify applications. +Ask your deployment administrator for the License Key and HTTP trace URL, using [Alibaba Cloud's connection instructions](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin). They should choose the region and network address that your Dify services can reach. - - Alibaba Cloud Monitor natively supports Python/Golang/Java applications through [LoongSuite](https://github.com/alibaba/loongsuite-python-agent) agents and open-source OpenTelemetry agents. In addition to one-click monitoring of Dify LLM applications, it also supports end-to-end observability of Dify components and their upstream and downstream dependencies through non-invasive agents. - - For more details, please refer to the [Cloud Monitor documentation](https://www.alibabacloud.com/help/en/cms/cloudmonitor-1-0/product-overview/what-is-cloudmonitor?spm=a3c0i.63551.2277339270.1.76c7112eeKEvSr). - +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Cloud Monitor**, click **Config** and enter the connection details: -## How to Configure Alibaba Cloud Monitor +| Field | Required | Value | +|:------|:---------|:------| +| **License Key** | Yes | The collector's authentication key, entered separately from the endpoint. | +| **Endpoint** | Yes | The collector's HTTP(S) base URL. An explicit port is allowed. | +| **App Name** | Yes | A name you choose for the application in the ARMS console. | -### 1. Get Alibaba Cloud Endpoint and License Key +From the HTTP trace URL, enter the part before `/adapt_` in **Endpoint** and the authentication token in **License Key**. For this example URL: -1. Log in to the [ARMS console](https://account.alibabacloud.com/login/login.htm?spm=5176.12901015-2.0.0.68d74b84XRatpU), and click **Integration Center** in the left navigation bar. -2. In the **Server-side Applications** area, click the **OpenTelemetry** card. -3. In the **OpenTelemetry** panel that appears, select **gRPC** as the export protocol, and select the connection method and region according to your actual deployment. +```text +https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces +``` - - ![Get Alibaba Cloud Access Point](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/get_endpoint.png) - +- **Endpoint**: `https://tracing-analysis-dc-hz.aliyuncs.com` +- **License Key**: `example-key` -4. Save the **Public Endpoint** and **Authentication Token (License Key)**. +Keep any port for the HTTP endpoint; a gRPC port such as `8090` won't work here. - - The Endpoint does not include a port number, for example `http://tracing-cn-heyuan.arms.aliyun.com`. - - -### 2. Configure Cloud Monitor in Dify - - - Requires Dify v1.6.0 or later. - - -1. Log in to the Dify console and navigate to the application you want to monitor. -2. Open **Monitoring** in the left navigation bar. -3. Click **Tracing app performance**, then click **Configure** in the **Cloud Monitor** area. - - - ![Configure Alibaba Cloud Monitor](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/config_cms.png) - - -4. In the dialog that appears, enter the **License Key** and **Endpoint** obtained in step 1, and customize the **App Name** (the application name displayed in the ARMS console), then click **Save & Enable**. - -## View Monitoring Data in Alibaba Cloud Monitor - -After configuration, debug or production data from applications in Dify can be monitored in Cloud Monitor. - -### Method 1: Jump to ARMS Console from Dify Application +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Cloud Monitor replaces the current selection. -In the Dify console, select an application with tracing enabled, go to **Tracing Configuration**, and click **View** in the **Cloud Monitor** area. +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. -### Method 2: View Directly in ARMS Console +## What Dify Sends -Go to the corresponding Dify application in the **LLM Application Monitoring > Application List** page of the ARMS console. +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. -## Access More Data +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. -Cloud Monitor provides multi-language non-invasive agents that support accessing various components of the Dify cluster to achieve end-to-end tracing. +In Alibaba Cloud Monitor, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill the platform's built-in cost fields. -| Dify Component | Agent | Details | -|----------------|-------|---------| -| Nginx | OpenTelemetry Agent | [Use OpenTelemetry for Nginx Tracing](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx?spm=a2c63.l28256.help-menu-search-90275.d_1) | -| API | LoongSuite-Python Agent | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | -| Sandbox | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -| Worker | OpenTelemetry Agent | [Submit Python Application Data via OpenTelemetry](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications?spm=a2c63.p38356.help-menu-90275.d_2_0_5_0.18ee53a4EGoGuS) | -| Plugin-Daemon | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | +### Include Agent Calls and Content -## Monitoring Data List - -Cloud Monitor supports collecting data from Dify's Workflow/Chatflow/Chat/Agent applications, including execution details of workflows and workflow nodes, covering model calls, tool calls, knowledge retrieval, execution details of various process nodes, as well as metadata such as conversations and user information. - -### Workflow/Chatflow Trace Information - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowAlibaba Cloud Monitor Trace
workflow\_idUnique identifier of the Workflow
conversation\_idConversation ID
workflow\_run\_idID of this run
tenant\_idTenant ID
elapsed\_timeDuration of this run
statusRun status
versionWorkflow version
total\_tokensTotal tokens used in this run
file\_listList of processed files
triggered\_fromSource that triggered this run
workflow\_run\_inputsInput data for this run
workflow\_run\_outputsOutput data for this run
errorErrors that occurred during this run
queryQuery used during runtime
workflow\_app\_log\_idWorkflow application log ID
message\_idAssociated message ID
start\_timeRun start time
end\_timeRun end time
- -**Workflow Trace Metadata** - -* workflow\_id - Unique identifier of the Workflow -* conversation\_id - Conversation ID -* workflow\_run\_id - ID of this run -* tenant\_id - Tenant ID -* elapsed\_time - Duration of this run -* status - Run status -* version - Workflow version -* total\_tokens - Total tokens used in this run -* file\_list - List of processed files -* triggered\_from - Trigger source - -### Message Trace Information + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MessageAlibaba Cloud Monitor Trace
message\_idMessage ID
message\_dataMessage data
user\_session\_idUser's session\_id
conversation\_modelConversation model
message\_tokensNumber of tokens in the message
answer\_tokensNumber of tokens in the answer
total\_tokensTotal tokens in message and answer
errorError information
inputsInput data
outputsOutput data
file\_listList of processed files
start\_timeStart time
end\_timeEnd time
message\_file\_dataFile data associated with the message
conversation\_modeConversation mode
+Under **Agent data capture** in the app's tracing settings: -**Message Trace Metadata** +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. -* conversation\_id - ID of the conversation to which the message belongs -* ls\_provider - Model provider -* ls\_model\_name - Model ID -* status - Message status -* from\_end\_user\_id - ID of the sending user -* from\_account\_id - ID of the sending account -* agent\_based - Whether it is agent-based -* workflow\_run\_id - Workflow run ID -* from\_source - Message source -* message\_id - Message ID + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + -### Dataset Retrieval Trace Information +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalAlibaba Cloud Monitor Trace
message\_idMessage ID
inputsInput content
documentsDocument data
start\_timeStart time
end\_timeEnd time
message\_dataMessage data
+## Verify a New Trace -**Dataset Retrieval Trace Metadata** +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Cloud Monitor** to open the ARMS LLM console. +3. Find the application name you entered, then locate the new trace by its run time and inspect its child spans. -* message\_id - Message ID -* ls\_provider - Model provider -* ls\_model\_name - Model ID -* status - Message status -* from\_end\_user\_id - ID of the sending user -* from\_account\_id - ID of the sending account -* agent\_based - Whether it is agent-based -* workflow\_run\_id - Workflow run ID -* from\_source - Message source +Traces may take time to appear after the run finishes. -### Tool Trace Information +## Troubleshooting - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolAlibaba Cloud Monitor Trace
message\_idMessage ID
tool\_nameTool name
start\_timeStart time
end\_timeEnd time
tool\_inputsTool inputs
tool\_outputsTool outputs
message\_dataMessage data
errorError information (if any)
inputsInput content of the message
outputsAnswer content of the message
tool\_configTool configuration
time\_costTime cost
tool\_parametersTool parameters
file\_urlURL of associated file
+ + + Saving tests collector access without creating a real trace. Confirm that Cloud Monitor is selected and tracing is enabled. In Alibaba Cloud Monitor, open the application name you configured. Then run the app again. -**Tool Trace Metadata** + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. -* message\_id - Message ID -* tool\_name - Tool name -* tool\_inputs - Tool inputs -* tool\_outputs - Tool outputs -* tool\_config - Tool configuration -* time\_cost - Time cost -* error - Error information -* tool\_parameters - Tool parameters -* message\_file\_id - Message file ID -* created\_by\_role - Creator role -* created\_user\_id - Creator user ID + For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + diff --git a/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx index 5de302b4f..2d605379d 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,568 +1,72 @@ --- title: Integrate with Arize sidebarTitle: Arize +description: Connect a Dify app to Arize, verify new traces, and choose which Agent data to send --- +## Connect Your App -### What is Arize +In Arize, get the API key and current Space ID from **Settings** > **API Keys**; see the [Arize quickstart](https://arize.com/docs/ax/quickstarts) for details. Choose a destination project name. To connect Phoenix instead, use the [Phoenix integration](/en/self-host/use-dify/monitor/integrations/integrate-phoenix). -[Arize AX](https://arize.com/products/ax/) is [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host)'s full-featured platform for observability, online and offline evaluation, monitoring, and experimentation in LLM and agent-driven applications. Built for production teams, AI-native companies, and enterprises, it runs as a managed cloud service or an enterprise self-hosted deployment. +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Arize**, click **Config** and enter the connection details: -If you'd rather run an open-source stack for local development, experimentation, or single-container self-hosting, set up the [Phoenix integration](/en/self-host/use-dify/monitor/integrations/integrate-phoenix) instead. +| Field | Required | Value | +|:------|:---------|:------| +| **API Key** | Yes | An Arize API key with ingestion access. | +| **Space ID** | Yes | The Arize space receiving the traces. | +| **Project** | Yes | The destination project name. | +| **Endpoint** | No | Defaults to `https://otlp.arize.com`. For a custom collector, use the address your administrator provides. | -Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality. +A custom **Endpoint** must accept OTLP/gRPC. Ask your administrator for its hostname and port, without an HTTP path such as `/v1/traces`. -### How to Configure Arize +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Arize replaces the current selection. -#### 1. Register/Login to [Arize](https://app.arize.com/auth/join) +Saved credentials are hidden when you edit. Leave **API Key** and **Space ID** blank to keep their saved values while **Endpoint** is unchanged. Re-enter both if you change the endpoint. -#### 2. Get your Arize API Key +## What Dify Sends -Retrieve your Arize API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. - - ![Arize API Key](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) - +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. -#### 3. Integrate Arize with Dify +In Arize, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill Arize's built-in cost fields. -Configure Arize in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. +### Include Agent Calls and Content - - ![Tracing App Performance](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) - + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + -After clicking configure, paste the **API Key**, **Space ID** and **project name** created in Arize into the configuration and save. +Under **Agent data capture** in the app's tracing settings: - - ![Configure Arize](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) - +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. -Once successfully saved, you can view the monitoring status on the current page. + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + - - ![Configure Arize](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) - +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. -### Monitoring Data List +## Verify a New Trace -#### **Workflow/Chatflow Trace Information** +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Arize**. If the shortcut is unavailable, open your Arize space and project directly. +3. Find the new trace by its run time and open it to inspect its child spans. -**Used to track workflows and chatflows** +Traces may take time to appear after the run finishes. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowArize Trace
workflow_app_log_id/workflow_run_idid
user_session_id- placed in metadata
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**Workflow Trace Info** +## Troubleshooting -- workflow_id - Unique identifier of the workflow -- conversation_id - Conversation ID -- workflow_run_id - ID of the current run -- tenant_id - Tenant ID -- elapsed_time - Time taken for the current run -- status - Run status -- version - Workflow version -- total_tokens - Total tokens used in the current run -- file_list - List of processed files -- triggered_from - Source that triggered the current run -- workflow_run_inputs - Input data for the current run -- workflow_run_outputs - Output data for the current run -- error - Errors encountered during the current run -- query - Query used during the run -- workflow_app_log_id - Workflow application log ID -- message_id - Associated message ID -- start_time - Start time of the run -- end_time - End time of the run -- workflow node executions - Information about workflow node executions -- Metadata - - workflow_id - Unique identifier of the workflow - - conversation_id - Conversation ID - - workflow_run_id - ID of the current run - - tenant_id - Tenant ID - - elapsed_time - Time taken for the current run - - status - Run status - - version - Workflow version - - total_tokens - Total tokens used in the current run - - file_list - List of processed files - - triggered_from - Source that triggered the current run + + + Saving tests collector access without creating a real trace. Confirm that Arize is selected and tracing is enabled. In Arize, open the configured space and project. Then run the app again. -#### **Message Trace Information** + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The gRPC collector must be reachable from Dify's API and workers. Ask your administrator to check its hostname, port, and network access. Use a reachable server address: loopback addresses such as `localhost` aren't accepted. + + -**Used to track LLM-related conversations** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChatArize LLM
message_idid
user_session_id- placed in metadata
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**Message Trace Info** - -- message_id - Message ID -- message_data - Message data -- user_session_id - User session ID -- conversation_model - Conversation mode -- message_tokens - Number of tokens in the message -- answer_tokens - Number of tokens in the answer -- total_tokens - Total number of tokens in the message and answer -- error - Error information -- inputs - Input data -- outputs - Output data -- file_list - List of processed files -- start_time - Start time -- end_time - End time -- message_file_data - File data associated with the message -- conversation_mode - Conversation mode -- Metadata - - conversation_id - Conversation ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Moderation Trace Information** - -**Used to track conversation moderation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationArize Tool
user_id- placed in metadata
“moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**Moderation Trace Info** - -- message_id - Message ID -- user_id: User ID -- workflow_app_log_id - Workflow application log ID -- inputs - Moderation input data -- message_data - Message data -- flagged - Whether the content is flagged for attention -- action - Specific actions taken -- preset_response - Preset response -- start_time - Moderation start time -- end_time - Moderation end time -- Metadata - - message_id - Message ID - - action - Specific actions taken - - preset_response - Preset response - -#### **Suggested Question Trace Information** - -**Used to track suggested questions** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionArize LLM
user_id- placed in metadata
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**Message Trace Info** - -- message_id - Message ID -- message_data - Message data -- inputs - Input content -- outputs - Output content -- start_time - Start time -- end_time - End time -- total_tokens - Number of tokens -- status - Message status -- error - Error information -- from_account_id - ID of the sending account -- agent_based - Whether the message is agent-based -- from_source - Message source -- model_provider - Model provider -- model_id - Model ID -- suggested_question - Suggested question -- level - Status level -- status_message - Status message -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Dataset Retrieval Trace Information** - -**Used to track knowledge base retrieval** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalArize Retriever
user_id- placed in metadata
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**Dataset Retrieval Trace Info** - -- message_id - Message ID -- inputs - Input content -- documents - Document data -- start_time - Start time -- end_time - End time -- message_data - Message data -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Tool Trace Information** - -**Used to track tool invocation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolArize Tool
user_id- placed in metadata
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-#### **Tool Trace Info** - -- message_id - Message ID -- tool_name - Tool name -- start_time - Start time -- end_time - End time -- tool_inputs - Tool inputs -- tool_outputs - Tool outputs -- message_data - Message data -- error - Error information, if any -- inputs - Inputs for the message -- outputs - Outputs of the message -- tool_config - Tool configuration -- time_cost - Time cost -- tool_parameters - Tool parameters -- file_url - URL of the associated file -- Metadata - - message_id - Message ID - - tool_name - Tool name - - tool_inputs - Tool inputs - - tool_outputs - Tool outputs - - tool_config - Tool configuration - - time_cost - Time cost - - error - Error information, if any - - tool_parameters - Tool parameters - - message_file_id - Message file ID - - created_by_role - Role of the creator - - created_user_id - User ID of the creator - -**Generate Name Trace Information** - -**Used to track conversation title generation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NameArize Tool
user_id- placed in metadata
"generate_conversation_name"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["generate_name"]tags
-**Generate Name Trace Info** - -- conversation_id - Conversation ID -- inputs - Input data -- outputs - Generated conversation name -- start_time - Start time -- end_time - End time -- tenant_id - Tenant ID -- Metadata - - conversation_id - Conversation ID - - tenant_id - Tenant ID +For help evaluating the traces you collect, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/). diff --git a/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index 61a9f706f..f05ecd3c5 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,642 +1,75 @@ --- title: Integrate with Langfuse sidebarTitle: Langfuse +description: Connect a Dify app to Langfuse, verify new traces, and choose which Agent data to send --- -### What is Langfuse +## Connect Your App -Langfuse is an open-source LLM engineering platform that helps teams collaborate on debugging, analyzing, and iterating their applications. +Create a Langfuse project and get its [API keys](https://langfuse.com/faq/all/where-are-langfuse-api-keys) from **Project Settings** > **API Keys**. For Langfuse Cloud, choose the [base URL for your region](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url) without the `/api/public` suffix. For a self-hosted instance, ask its administrator for the base URL. - - Introduction to Langfuse: [https://langfuse.com/](https://langfuse.com/) - +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Langfuse**, click **Config** and enter the connection details: -### How to Configure Langfuse +| Field | Required | Value | +|:------|:---------|:------| +| **Secret Key** | Yes | The project's secret key. | +| **Public Key** | Yes | The matching public key. | +| **Host** | Yes | Your Langfuse instance's HTTP(S) base URL. | -1. Register and log in to Langfuse on the [official website](https://langfuse.com/) -2. Create a project in Langfuse. After logging in, click **New** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring. + +This integration requires Langfuse's legacy ingestion API, `/api/public/ingestion`, to receive trace data. Langfuse v4 deployments using `events_only` mode don't accept these traces. Check [Langfuse's ingestion compatibility](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api) with your Langfuse administrator before connecting. + - - ![Create a Project in Langfuse](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) - +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Langfuse replaces the current selection. -Edit a name for the project. +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Host** is unchanged. Re-enter them if you change the destination. - - ![Create a Project in Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) - +## What Dify Sends -3. Create project API credentials. In the left sidebar of the project, click **Settings** to open the settings. +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. - - ![Create Project API Credentials](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) - +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. -In Settings, click **Create API Keys** to create project API credentials. +In Langfuse, open a generation to inspect a model call's captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. - - ![Create Project API Credentials](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) - +### Include Agent Calls and Content -Copy and save the **Secret Key**, **Public Key**, and **Host**. + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + - - ![Get API Key Configuration](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) - +Under **Agent data capture** in the app's tracing settings: -4. Configure Langfuse in Dify. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. - - ![Configure Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) - + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + -After clicking configure, paste the **Secret Key, Public Key, Host** created in Langfuse into the configuration and save. +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. - - ![Configure Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) - +## Verify a New Trace -Once successfully saved, you can view the status on the current page. If it shows as started, it is being monitored. +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Langfuse** to open the configured project. +3. Find the new trace by its run time. Open it to inspect the model generations or node spans. - - ![View Configuration Status](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) - +Traces may take time to appear after the run finishes. -### View Monitoring Data in Langfuse +## Troubleshooting -After configuration, debugging or production data of the application in Dify can be viewed in Langfuse. + + + Saving the configuration checks project access. Confirm that Langfuse is selected and tracing is enabled. Then run the app again and check the same project. - - ![Configuration, Debugging or Production Data of the Application in Dify Can Be](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) - + Ask your administrator to check worker logs for ingestion errors and confirm that Langfuse accepts data through `/api/public/ingestion`. They should also check the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. - - ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) - + For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + -### List of monitoring data - -#### Trace the information of Workflow and Chatflow - -**Tracing Workflow and Chatflow** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowLangFuse Trace
workflow\_app\_log\_id/workflow\_run\_idid
user\_session\_iduser\_id
{"workflow_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
Model token consumptionusage
metadatametadata
errorlevel
errorstatus\_message
\[workflow]tags
\["message", conversation\_mode]session\_id
conversion\_idparent\_observation\_id
-**Workflow Trace Info** - -* workflow\_id - Unique ID of Workflow -* conversation\_id - Conversation ID -* workflow\_run\_id - Workflow ID of this runtime -* tenant\_id - Tenant ID -* elapsed\_time - Elapsed time at this runtime -* status - Runtime status -* version - Workflow version -* total\_tokens - Total token used at this runtime -* file\_list - List of files processed -* triggered\_from - Source that triggered this runtime -* workflow\_run\_inputs - Input of this workflow -* workflow\_run\_outputs - Output of this workflow -* error - Error Message -* query - Queries used at runtime -* workflow\_app\_log\_id - Workflow Application Log ID -* message\_id - Relevant Message ID -* start\_time - Start time of this runtime -* end\_time - End time of this runtime -* workflow node executions - Workflow node runtime information -* Metadata - * workflow\_id - Unique ID of Workflow - * conversation\_id - Conversation ID - * workflow\_run\_id - Workflow ID of this runtime - * tenant\_id - Tenant ID - * elapsed\_time - Elapsed time at this runtime - * status - Operational state - * version - Workflow version - * total\_tokens - Total token used at this runtime - * file\_list - List of files processed - * triggered\_from - Source that triggered this runtime - -#### Message Trace Info - -**For trace llm conversation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MessageLangFuse Generation/Trace
message\_idid
user\_session\_iduser\_id
{"message_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
Model token consumptionusage
metadatametadata
errorlevel
errorstatus\_message
\["message", conversation\_mode]tags
conversation\_idsession\_id
conversion\_idparent\_observation\_id
-**Message Trace Info** - -* message\_id - Message ID -* message\_data - Message data -* user\_session\_id - Session ID for user -* conversation\_model - Conversation model -* message\_tokens - Message tokens -* answer\_tokens - Answer Tokens -* total\_tokens - Total Tokens from Message and Answer -* error - Error Message -* inputs - Input data -* outputs - Output data -* file\_list - List of files processed -* start\_time - Start time -* end\_time - End time -* message\_file\_data - Message of relevant file data -* conversation\_mode - Conversation mode -* Metadata - * conversation\_id - Conversation ID - * ls\_provider - Model provider - * ls\_model\_name - Model ID - * status - Message status - * from\_end\_user\_id - Sending user's ID - * from\_account\_id - Sending account's ID - * agent\_based - Whether agent based - * workflow\_run\_id - Workflow ID of this runtime - * from\_source - Message source - * message\_id - Message ID - -#### Moderation Trace Information - -**Used to track conversation moderation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationLangFuse Generation/Trace
user\_iduser\_id
moderationname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[moderation]tags
message\_idparent\_observation\_id
-**Message Trace Info** - -* message\_id - Message ID -* user\_id - user ID -* workflow\_app\_log\_id workflow\_app\_log\_id -* inputs - Input data for review -* message\_data - Message Data -* flagged - Whether it is flagged for attention -* action - Specific actions to implement -* preset\_response - Preset response -* start\_time - Start time of review -* end\_time - End time of review -* Metadata - * message\_id - Message ID - * action - Specific actions to implement - * preset\_response - Preset response - -#### Suggested Question Trace Information - -**Used to track suggested questions** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionLangFuse Generation/Trace
user\_iduser\_id
suggested\_questionname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[suggested\_question]tags
message\_idparent\_observation\_id
-**Message Trace Info** - -* message\_id - Message ID -* message\_data - Message data -* inputs - Input data -* outputs - Output data -* start\_time - Start time -* end\_time - End time -* total\_tokens - Total tokens -* status - Message Status -* error - Error Message -* from\_account\_id - Sending account ID -* agent\_based - Whether agent based -* from\_source - Message source -* model\_provider - Model provider -* model\_id - Model ID -* suggested\_question - Suggested question -* level - Status level -* status\_message - Message status -* Metadata - * message\_id - Message ID - * ls\_provider - Model Provider - * ls\_model\_name - Model ID - * status - Message status - * from\_end\_user\_id - Sending user's ID - * from\_account\_id - Sending Account ID - * workflow\_run\_id - Workflow ID of this runtime - * from\_source - Message source - -#### Dataset Retrieval Trace Information - -**Used to track knowledge base retrieval** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalLangFuse Generation/Trace
user\_iduser\_id
dataset\_retrievalname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[dataset\_retrieval]tags
message\_idparent\_observation\_id
-**Dataset Retrieval Trace Info** - -* message\_id - Message ID -* inputs - Input Message -* documents - Document data -* start\_time - Start time -* end\_time - End time -* message\_data - Message data -* Metadata - * message\_id - Message ID - * ls\_provider - Model Provider - * ls\_model\_name - Model ID - * status - Model status - * from\_end\_user\_id - Sending user's ID - * from\_account\_id - Sending account's ID - * agent\_based - Whether agent based - * workflow\_run\_id - Workflow ID of this runtime - * from\_source - Message Source - -#### Tool Trace Information - -**Used to track tool invocation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolLangFuse Generation/Trace
user\_iduser\_id
tool\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\["tool", tool\_name]tags
message\_idparent\_observation\_id
-**Tool Trace Info** - -* message\_id - Message ID -* tool\_name - Tool Name -* start\_time - Start time -* end\_time - End time -* tool\_inputs - Tool inputs -* tool\_outputs - Tool outputs -* message\_data - Message data -* error - Error Message, if exist -* inputs - Input of Message -* outputs - Output of Message -* tool\_config - Tool config -* time\_cost - Time cost -* tool\_parameters - Tool Parameters -* file\_url - URL of relevant files -* Metadata - * message\_id - Message ID - * tool\_name - Tool Name - * tool\_inputs - Tool inputs - * tool\_outputs - Tool outputs - * tool\_config - Tool config - * time\_cost - Time. cost - * error - Error Message - * tool\_parameters - Tool parameters - * message\_file\_id - Message file ID - * created\_by\_role - Created by role - * created\_user\_id - Created user ID - -#### Generate Name Trace - -**Used to track conversation title generation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NameLangFuse Generation/Trace
user\_iduser\_id
generate\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[generate\_name]tags
-**Generate Name Trace Info** - -* conversation\_id - Conversation ID -* inputs - Input data -* outputs - Generated session name -* start\_time - Start time -* end\_time - End time -* tenant\_id - Tenant ID -* Metadata - * conversation\_id - Conversation ID - * tenant\_id - Tenant ID - - -### Langfuse Prompt Management - -The [Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) (community maintained) lets you use prompts that are [managed and versioned in Langfuse](https://langfuse.com/docs/prompt-management/get-started) in your Dify applications, enhancing your LLM application development workflow. Key features include: - -- **Get Prompt**: Fetch specific prompts managed in Langfuse. -- **Search Prompts**: Search for prompts in Langfuse using various filters. -- **Update Prompt**: Create new versions of prompts in Langfuse and set tags/labels. - -This integration streamlines the process of managing and versioning your prompts, contributing to more efficient development and iteration cycles. You can find the plugin and installation instructions [here](https://github.com/gao-ai-com/dify-plugin-langfuse). +To use prompts managed in Langfuse, see the community-maintained [Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) for installation and usage. diff --git a/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index b3f5d4705..5db1b7eb9 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,648 +1,71 @@ --- title: Integrate with LangSmith sidebarTitle: LangSmith +description: Connect a Dify app to LangSmith, verify new traces, and choose which Agent data to send --- +## Connect Your App -### What is LangSmith +Get a [LangSmith API key](https://docs.langchain.com/langsmith/create-account-api-key) with access to read projects and send traces in the target workspace. Choose the exact project name you want to use. -LangSmith is a platform for building production-grade LLM applications. It is used for developing, collaborating, testing, deploying, and monitoring LLM applications. +In the Dify app, open **Monitoring** > **Tracing app performance**. For **LangSmith**, click **Config** and enter the connection details: - -For more details, please refer to [LangSmith](https://www.langchain.com/langsmith). - +| Field | Required | Value | +|:------|:---------|:------| +| **API Key** | Yes | A key with project read and trace write access. | +| **Project** | Yes | The project name. LangSmith creates it on the first trace if it doesn't exist. | +| **Endpoint** | No | Defaults to `https://api.smith.langchain.com`. A custom API endpoint must use HTTPS; keep any required path prefix. | -### How to Configure LangSmith +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting LangSmith replaces the current selection. -#### 1. Register/Login to [LangSmith](https://www.langchain.com/langsmith) +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. -#### 2. Create a Project +## What Dify Sends -Create a project in LangSmith. After logging in, click **New Project** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring. +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. - - ![Create a Project in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) - +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. -Once created, you can view all created projects in the Projects section. +In LangSmith, open a model run to inspect its captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. - - ![View Created Projects in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) - +### Include Agent Calls and Content -#### 3. Create Project Credentials + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + -Find the project settings **Settings** in the left sidebar. +Under **Agent data capture** in the app's tracing settings: - - ![Project Settings](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) - +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. -Click **Create API Key** to create project credentials. + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + - - ![Create a Project API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) - +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. -Select **Personal Access Token** for subsequent API authentication. +## Verify a New Trace - - ![Create an API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) - +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **LangSmith**. +3. In the configured project, find the new run by its run time and inspect its child runs. -Copy and save the created API key. +Traces may take time to appear after the run finishes. - - ![Copy API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) - +If **View** opens the project list after the first trace arrives, save the configuration again to update the project link. -#### 4. Integrate LangSmith with Dify +## Troubleshooting -Configure LangSmith in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + Saving checks project access; a new project is created only when its first trace arrives. Confirm that LangSmith is selected and tracing is enabled. Then run the app again and check the exact project name you configured. - - ![Tracing App Performance](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/b6c7e5d4c2ca2092d59465cca27bc69c.png) - + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. -After clicking configure, paste the **API Key** and **project name** created in LangSmith into the configuration and save. - - - ![Configure LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/93dfabcadb7b2ff597f54beb5e642124.png) - - - -The configured project name needs to match the project set in LangSmith. If the project names do not match, LangSmith will automatically create a new project during data synchronization. - - -Once successfully saved, you can view the monitoring status on the current page. - - - ![View Configuration Status](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/43369dc4de8f606c166fae2efab97d73.png) - - -### View Monitoring Data in LangSmith - -Once configured, the debug or production data from applications within Dify can be monitored in LangSmith. - - - ![Debugging Applications in Dify](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a1370fdbb79257cba31a565ac6764802.png) - - -When you switch to LangSmith, you can view detailed operation logs of Dify applications in the dashboard. - - - ![Viewing Application Data in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) - - -Detailed LLM operation logs through LangSmith will help you optimize the performance of your Dify application. - - - ![Viewing Application Data in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/beeb4ee50c80de8db7400c1f65727c8c.png) - - -### Monitoring Data List - -#### **Workflow/Chatflow Trace Information** - -**Used to track workflows and chatflows** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowLangSmith Chain
workflow\_app\_log\_id/workflow\_run\_idid
user\_session\_id- placed in metadata
{"workflow_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
Model token consumptionusage\_metadata
metadataextra
errorerror
\[workflow]tags
"conversation\_id/none for workflow"conversation\_id in metadata
conversion\_idparent\_run\_id
-**Workflow Trace Info** - -* workflow\_id - Unique identifier of the workflow -* conversation\_id - Conversation ID -* workflow\_run\_id - ID of the current run -* tenant\_id - Tenant ID -* elapsed\_time - Time taken for the current run -* status - Run status -* version - Workflow version -* total\_tokens - Total tokens used in the current run -* file\_list - List of processed files -* triggered\_from - Source that triggered the current run -* workflow\_run\_inputs - Input data for the current run -* workflow\_run\_outputs - Output data for the current run -* error - Errors encountered during the current run -* query - Query used during the run -* workflow\_app\_log\_id - Workflow application log ID -* message\_id - Associated message ID -* start\_time - Start time of the run -* end\_time - End time of the run -* workflow node executions - Information about workflow node executions -* Metadata - * workflow\_id - Unique identifier of the workflow - * conversation\_id - Conversation ID - * workflow\_run\_id - ID of the current run - * tenant\_id - Tenant ID - * elapsed\_time - Time taken for the current run - * status - Run status - * version - Workflow version - * total\_tokens - Total tokens used in the current run - * file\_list - List of processed files - * triggered\_from - Source that triggered the current run - -#### **Message Trace Information** - -**Used to track LLM-related conversations** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChatLangSmith LLM
message\_idid
user\_session\_id- placed in metadata
{'"message_{id}"'}name
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
Model token consumptionusage\_metadata
metadataextra
errorerror
\["message", conversation\_mode]tags
conversation\_idconversation\_id in metadata
conversion\_idparent\_run\_id
-**Message Trace Info** - -* message\_id - Message ID -* message\_data - Message data -* user\_session\_id - User session ID -* conversation\_model - Conversation mode -* message\_tokens - Number of tokens in the message -* answer\_tokens - Number of tokens in the answer -* total\_tokens - Total number of tokens in the message and answer -* error - Error information -* inputs - Input data -* outputs - Output data -* file\_list - List of processed files -* start\_time - Start time -* end\_time - End time -* message\_file\_data - File data associated with the message -* conversation\_mode - Conversation mode -* Metadata - * conversation\_id - Conversation ID - * ls\_provider - Model provider - * ls\_model\_name - Model ID - * status - Message status - * from\_end\_user\_id - ID of the sending user - * from\_account\_id - ID of the sending account - * agent\_based - Whether the message is agent-based - * workflow\_run\_id - Workflow run ID - * from\_source - Message source - -#### **Moderation Trace Information** - -**Used to track conversation moderation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationLangSmith Tool
user\_id- placed in metadata
“moderation"name
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra
\[moderation]tags
message\_idparent\_run\_id
-**Moderation Trace Info** - -* message\_id - Message ID -* user\_id: User ID -* workflow\_app\_log\_id - Workflow application log ID -* inputs - Moderation input data -* message\_data - Message data -* flagged - Whether the content is flagged for attention -* action - Specific actions taken -* preset\_response - Preset response -* start\_time - Moderation start time -* end\_time - Moderation end time -* Metadata - * message\_id - Message ID - * action - Specific actions taken - * preset\_response - Preset response - -#### **Suggested Question Trace Information** - -**Used to track suggested questions** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionLangSmith LLM
user\_id- placed in metadata
suggested\_questionname
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra
\[suggested\_question]tags
message\_idparent\_run\_id
-**Message Trace Info** - -* message\_id - Message ID -* message\_data - Message data -* inputs - Input content -* outputs - Output content -* start\_time - Start time -* end\_time - End time -* total\_tokens - Number of tokens -* status - Message status -* error - Error information -* from\_account\_id - ID of the sending account -* agent\_based - Whether the message is agent-based -* from\_source - Message source -* model\_provider - Model provider -* model\_id - Model ID -* suggested\_question - Suggested question -* level - Status level -* status\_message - Status message -* Metadata - * message\_id - Message ID - * ls\_provider - Model provider - * ls\_model\_name - Model ID - * status - Message status - * from\_end\_user\_id - ID of the sending user - * from\_account\_id - ID of the sending account - * workflow\_run\_id - Workflow run ID - * from\_source - Message source - -#### **Dataset Retrieval Trace Information** - -**Used to track knowledge base retrieval** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalLangSmith Retriever
user\_id- placed in metadata
dataset\_retrievalname
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra
\[dataset\_retrieval]tags
message\_idparent\_run\_id
-**Dataset Retrieval Trace Info** - -* message\_id - Message ID -* inputs - Input content -* documents - Document data -* start\_time - Start time -* end\_time - End time -* message\_data - Message data -* Metadata - * message\_id - Message ID - * ls\_provider - Model provider - * ls\_model\_name - Model ID - * status - Message status - * from\_end\_user\_id - ID of the sending user - * from\_account\_id - ID of the sending account - * agent\_based - Whether the message is agent-based - * workflow\_run\_id - Workflow run ID - * from\_source - Message source - -#### **Tool Trace Information** - -**Used to track tool invocation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolLangSmith Tool
user\_id- placed in metadata
tool\_namename
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra
\["tool", tool\_name]tags
message\_idparent\_run\_id
-#### **Tool Trace Info** - -* message\_id - Message ID -* tool\_name - Tool name -* start\_time - Start time -* end\_time - End time -* tool\_inputs - Tool inputs -* tool\_outputs - Tool outputs -* message\_data - Message data -* error - Error information, if any -* inputs - Inputs for the message -* outputs - Outputs of the message -* tool\_config - Tool configuration -* time\_cost - Time cost -* tool\_parameters - Tool parameters -* file\_url - URL of the associated file -* Metadata - * message\_id - Message ID - * tool\_name - Tool name - * tool\_inputs - Tool inputs - * tool\_outputs - Tool outputs - * tool\_config - Tool configuration - * time\_cost - Time cost - * error - Error information, if any - * tool\_parameters - Tool parameters - * message\_file\_id - Message file ID - * created\_by\_role - Role of the creator - * created\_user\_id - User ID of the creator - -**Generate Name Trace Information** - -**Used to track conversation title generation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NameLangSmith Tool
user\_id- placed in metadata
generate\_namename
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra
\[generate\_name]tags
-**Generate Name Trace Info** - -* conversation\_id - Conversation ID -* inputs - Input data -* outputs - Generated conversation name -* start\_time - Start time -* end\_time - End time -* tenant\_id - Tenant ID -* Metadata - * conversation\_id - Conversation ID - * tenant\_id - Tenant ID + For a private-network endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + diff --git a/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx index 2dbc0d539..fc482102e 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,586 +1,70 @@ --- title: Integrate with Opik sidebarTitle: Opik +description: Connect a Dify app to Opik, verify new traces, and choose which Agent data to send --- +## Connect Your App -### What is Opik +Get an API key for hosted Opik, or use your own Opik instance. See [Opik's Dify integration guide](https://www.comet.com/docs/opik/integrations/dify) for account setup. For a named workspace on your own server, ask its administrator which name to use. -Opik is an open-source platform designed for evaluating, testing, and monitoring large language model (LLM) applications. Developed by Comet, it aims to facilitate more intuitive collaboration, testing, and monitoring of LLM-based applications. +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Opik**, click **Config** and enter the connection details: - -For more details, please refer to [Opik](https://www.comet.com/site/products/opik/). - +| Field | Required | Value | +|:------|:---------|:------| +| **API Key** | For hosted Opik | Your account API key. Leave blank only if your server uses no authentication. | +| **Project** | No | The project name; Opik creates it on the first trace. If blank, Dify uses `Default Project`. | +| **Workspace** | No | An existing workspace. If blank, Dify uses the account default, or `default` for an unauthenticated open-source server. | +| **Url** | No | Defaults to `https://www.comet.com/opik/api/`. A custom HTTP(S) URL must end in `/api/`. | ---- - -### How to Configure Opik - -#### 1. Register/Login to [Opik](https://www.comet.com/signup?from=llm) - -#### 2. Get your Opik API Key - -Retrieve your Opik API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: - - - ![Opik API Key](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) - - -#### 3. Integrate Opik with Dify - -Configure Opik in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. - - - ![Tracing App Performance](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) - - -After clicking configure, paste the **API Key** and **project name** created in Opik into the configuration and save. - - - ![Configure Opik](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) - - -Once successfully saved, you can view the monitoring status on the current page. - -### View Monitoring Data in Opik - -Once configured, you can debug or use the Dify application as usual. All usage history can be monitored in Opik. - - - ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) - - -When you switch to Opik, you can view detailed operation logs of Dify applications in the dashboard. - - - ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) - - -Detailed LLM operation logs through Opik will help you optimize the performance of your Dify application. - - - ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) - - -### Monitoring Data List - -#### **Workflow/Chatflow Trace Information** - -**Used to track workflows and chatflows** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowOpik Trace
workflow_app_log_id/workflow_run_idid
user_session_id- placed in metadata
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**Workflow Trace Info** - -- workflow_id - Unique identifier of the workflow -- conversation_id - Conversation ID -- workflow_run_id - ID of the current run -- tenant_id - Tenant ID -- elapsed_time - Time taken for the current run -- status - Run status -- version - Workflow version -- total_tokens - Total tokens used in the current run -- file_list - List of processed files -- triggered_from - Source that triggered the current run -- workflow_run_inputs - Input data for the current run -- workflow_run_outputs - Output data for the current run -- error - Errors encountered during the current run -- query - Query used during the run -- workflow_app_log_id - Workflow application log ID -- message_id - Associated message ID -- start_time - Start time of the run -- end_time - End time of the run -- workflow node executions - Information about workflow node executions -- Metadata - - workflow_id - Unique identifier of the workflow - - conversation_id - Conversation ID - - workflow_run_id - ID of the current run - - tenant_id - Tenant ID - - elapsed_time - Time taken for the current run - - status - Run status - - version - Workflow version - - total_tokens - Total tokens used in the current run - - file_list - List of processed files - - triggered_from - Source that triggered the current run - -#### **Message Trace Information** - -**Used to track LLM-related conversations** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChatOpik LLM
message_idid
user_session_id- placed in metadata
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**Message Trace Info** - -- message_id - Message ID -- message_data - Message data -- user_session_id - User session ID -- conversation_model - Conversation mode -- message_tokens - Number of tokens in the message -- answer_tokens - Number of tokens in the answer -- total_tokens - Total number of tokens in the message and answer -- error - Error information -- inputs - Input data -- outputs - Output data -- file_list - List of processed files -- start_time - Start time -- end_time - End time -- message_file_data - File data associated with the message -- conversation_mode - Conversation mode -- Metadata - - conversation_id - Conversation ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Moderation Trace Information** - -**Used to track conversation moderation** +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Opik replaces the current selection. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationOpik Tool
user_id- placed in metadata
“moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**Moderation Trace Info** +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Url** is unchanged. Re-enter them if you change the destination. -- message_id - Message ID -- user_id: User ID -- workflow_app_log_id - Workflow application log ID -- inputs - Moderation input data -- message_data - Message data -- flagged - Whether the content is flagged for attention -- action - Specific actions taken -- preset_response - Preset response -- start_time - Moderation start time -- end_time - Moderation end time -- Metadata - - message_id - Message ID - - action - Specific actions taken - - preset_response - Preset response +## What Dify Sends -#### **Suggested Question Trace Information** +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. -**Used to track suggested questions** +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionOpik LLM
user_id- placed in metadata
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**Message Trace Info** +In Opik, open an LLM span to inspect a model call's captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. -- message_id - Message ID -- message_data - Message data -- inputs - Input content -- outputs - Output content -- start_time - Start time -- end_time - End time -- total_tokens - Number of tokens -- status - Message status -- error - Error information -- from_account_id - ID of the sending account -- agent_based - Whether the message is agent-based -- from_source - Message source -- model_provider - Model provider -- model_id - Model ID -- suggested_question - Suggested question -- level - Status level -- status_message - Status message -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - workflow_run_id - Workflow run ID - - from_source - Message source +### Include Agent Calls and Content -#### **Dataset Retrieval Trace Information** + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + -**Used to track knowledge base retrieval** +Under **Agent data capture** in the app's tracing settings: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalOpik Retriever
user_id- placed in metadata
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**Dataset Retrieval Trace Info** +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. -- message_id - Message ID -- inputs - Input content -- documents - Document data -- start_time - Start time -- end_time - End time -- message_data - Message data -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + -#### **Tool Trace Information** +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. -**Used to track tool invocation** +## Verify a New Trace - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolOpik Tool
user_id- placed in metadata
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-#### **Tool Trace Info** +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Opik**. Select the configured workspace and project if the link opens the console. +3. Find the new trace by its run time and open it to inspect its spans. -- message_id - Message ID -- tool_name - Tool name -- start_time - Start time -- end_time - End time -- tool_inputs - Tool inputs -- tool_outputs - Tool outputs -- message_data - Message data -- error - Error information, if any -- inputs - Inputs for the message -- outputs - Outputs of the message -- tool_config - Tool configuration -- time_cost - Time cost -- tool_parameters - Tool parameters -- file_url - URL of the associated file -- Metadata - - message_id - Message ID - - tool_name - Tool name - - tool_inputs - Tool inputs - - tool_outputs - Tool outputs - - tool_config - Tool configuration - - time_cost - Time cost - - error - Error information, if any - - tool_parameters - Tool parameters - - message_file_id - Message file ID - - created_by_role - Role of the creator - - created_user_id - User ID of the creator +Traces may take time to appear after the run finishes. -**Generate Name Trace Information** +## Troubleshooting -**Used to track conversation title generation** + + + Saving checks workspace access; Opik creates the project on its first trace. Confirm that Opik is selected and tracing is enabled. In Opik, open the configured workspace and project. Then run the app again. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NameOpik Tool
user_id- placed in metadata
"generate_conversation_name"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["generate_name"]tags
-**Generate Name Trace Info** + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. -- conversation_id - Conversation ID -- inputs - Input data -- outputs - Generated conversation name -- start_time - Start time -- end_time - End time -- tenant_id - Tenant ID -- Metadata - - conversation_id - Conversation ID - - tenant_id - Tenant ID + For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + diff --git a/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index a7e6df8fd..246cd5d84 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,616 +1,73 @@ --- title: Integrate with Phoenix sidebarTitle: Phoenix +description: Connect a Dify app to Phoenix, verify new traces, and choose which Agent data to send --- +## Connect Your App -### What is Phoenix +Use a Phoenix instance your Dify services can reach, either self-hosted or Phoenix Cloud. If it requires authentication, get an [API key](https://arize.com/docs/phoenix/settings/api-keys) that can read projects and send traces. To connect Arize instead, follow the [Arize integration](/en/self-host/use-dify/monitor/integrations/integrate-arize). -[Arize Phoenix](https://arize.com/phoenix/) is the open-source, OpenTelemetry-based platform from [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) for observability, evaluation, prompt engineering, and experimentation with LLM workflows and agents. +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Phoenix**, click **Config** and enter the connection details: -Run Phoenix locally during development, self-host it on your own infrastructure (a single container is enough to start), or use Arize's hosted [Phoenix Cloud](#how-to-configure-phoenix-cloud). +| Field | Required | Value | +|:------|:---------|:------| +| **API Key** | When authentication is enabled | The key for your instance or Phoenix Cloud space. Leave blank for an unauthenticated server. | +| **Project** | Yes | The destination project name. | +| **Endpoint** | No | Your Phoenix base URL. Replace the default `https://app.phoenix.arize.com` with your Cloud space or self-hosted instance URL, including any path prefix. | -If you need the full-featured platform built for production teams, AI-native companies, and enterprises, set up [Arize AX](https://arize.com/products/ax/) through the [Arize integration](/en/self-host/use-dify/monitor/integrations/integrate-arize) instead. +For Phoenix Cloud, copy your space's hostname, such as `https://app.phoenix.arize.com/s/`. See [Find Your Phoenix Endpoint](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint) for where to find it. Enter the base URL without `/v1/traces`; Dify adds that path. -Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality. +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Phoenix replaces the current selection. -### How to Configure Phoenix +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. -#### 1. Register/Login to [Phoenix](https://app.arize.com/auth/phoenix/signup) +## What Dify Sends -#### 2. Get your Phoenix API Key +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. -Retrieve your Phoenix API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. - - ![Phoenix API Key](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) - +In Phoenix, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill Phoenix's built-in cost fields. -#### 3. Integrate Phoenix with Dify +### Include Agent Calls and Content -Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + - - ![Tracing App Performance](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - +Under **Agent data capture** in the app's tracing settings: -After clicking configure, paste the **API Key** and **project name** created in Phoenix into the configuration and save. +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. - - ![Configure Phoenix](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + -Once successfully saved, you can view the monitoring status on the current page. +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. - - ![Configure Phoenix](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - +## Verify a New Trace -### How to Configure Phoenix Cloud +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Phoenix** to open the configured project. +3. Find the new trace by its run time and open it to inspect its child spans. -#### 1. Register/Login to [Phoenix Cloud](https://app.arize.com/auth/phoenix/signup) +Traces may take time to appear after the run finishes. -#### 2. Create your Phoenix Space +## Troubleshooting -You can create your Phoenix Space from the user menu at the top-right. Click on **Create Space**, then provide a unique URL identifier for your space: + + + Saving confirms access to read projects; it does not send a trace. Confirm that Phoenix is selected and tracing is enabled. Then run the app again and check the configured project. - - ![Phoenix Cloud Create Space](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) - + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. -Once successfully saved, you can view the space status on the overview page. + For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + - - ![Phoenix Cloud Space Overview](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) - - -#### 3. Create your Phoenix API Key - -After launching your space, you can create your Phoenix API Key from the **Settings** option in the user menu at the bottom-left. Click on **System Key**, then provide a name for your Phoenix API Key: - - - ![Phoenix Cloud API Key](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) - - -#### 4. Integrate Phoenix Cloud with Dify - -Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. - - - ![Tracing App Performance](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - - -After clicking configure, paste the **API Key** and **project name** along with **Space Hostname** created in Phoenix Cloud into the configuration and save. - - - ![Configure Phoenix](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - - -Once successfully saved, you can view the monitoring status on the current page. - - - ![Configure Phoenix](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - - -### Monitoring Data List - -#### **Workflow/Chatflow Trace Information** - -**Used to track workflows and chatflows** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowPhoenix Trace
workflow_app_log_id/workflow_run_idid
user_session_id- placed in metadata
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**Workflow Trace Info** - -- workflow_id - Unique identifier of the workflow -- conversation_id - Conversation ID -- workflow_run_id - ID of the current run -- tenant_id - Tenant ID -- elapsed_time - Time taken for the current run -- status - Run status -- version - Workflow version -- total_tokens - Total tokens used in the current run -- file_list - List of processed files -- triggered_from - Source that triggered the current run -- workflow_run_inputs - Input data for the current run -- workflow_run_outputs - Output data for the current run -- error - Errors encountered during the current run -- query - Query used during the run -- workflow_app_log_id - Workflow application log ID -- message_id - Associated message ID -- start_time - Start time of the run -- end_time - End time of the run -- workflow node executions - Information about workflow node executions -- Metadata - - workflow_id - Unique identifier of the workflow - - conversation_id - Conversation ID - - workflow_run_id - ID of the current run - - tenant_id - Tenant ID - - elapsed_time - Time taken for the current run - - status - Run status - - version - Workflow version - - total_tokens - Total tokens used in the current run - - file_list - List of processed files - - triggered_from - Source that triggered the current run - -#### **Message Trace Information** - -**Used to track LLM-related conversations** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChatPhoenix LLM
message_idid
user_session_id- placed in metadata
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
Model token consumptionusage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**Message Trace Info** - -- message_id - Message ID -- message_data - Message data -- user_session_id - User session ID -- conversation_model - Conversation mode -- message_tokens - Number of tokens in the message -- answer_tokens - Number of tokens in the answer -- total_tokens - Total number of tokens in the message and answer -- error - Error information -- inputs - Input data -- outputs - Output data -- file_list - List of processed files -- start_time - Start time -- end_time - End time -- message_file_data - File data associated with the message -- conversation_mode - Conversation mode -- Metadata - - conversation_id - Conversation ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Moderation Trace Information** - -**Used to track conversation moderation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationPhoenix Tool
user_id- placed in metadata
“moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**Moderation Trace Info** - -- message_id - Message ID -- user_id: User ID -- workflow_app_log_id - Workflow application log ID -- inputs - Moderation input data -- message_data - Message data -- flagged - Whether the content is flagged for attention -- action - Specific actions taken -- preset_response - Preset response -- start_time - Moderation start time -- end_time - Moderation end time -- Metadata - - message_id - Message ID - - action - Specific actions taken - - preset_response - Preset response - -#### **Suggested Question Trace Information** - -**Used to track suggested questions** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionPhoenix LLM
user_id- placed in metadata
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**Message Trace Info** - -- message_id - Message ID -- message_data - Message data -- inputs - Input content -- outputs - Output content -- start_time - Start time -- end_time - End time -- total_tokens - Number of tokens -- status - Message status -- error - Error information -- from_account_id - ID of the sending account -- agent_based - Whether the message is agent-based -- from_source - Message source -- model_provider - Model provider -- model_id - Model ID -- suggested_question - Suggested question -- level - Status level -- status_message - Status message -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Dataset Retrieval Trace Information** - -**Used to track knowledge base retrieval** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalPhoenix Retriever
user_id- placed in metadata
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**Dataset Retrieval Trace Info** - -- message_id - Message ID -- inputs - Input content -- documents - Document data -- start_time - Start time -- end_time - End time -- message_data - Message data -- Metadata - - message_id - Message ID - - ls_provider - Model provider - - ls_model_name - Model ID - - status - Message status - - from_end_user_id - ID of the sending user - - from_account_id - ID of the sending account - - agent_based - Whether the message is agent-based - - workflow_run_id - Workflow run ID - - from_source - Message source - -#### **Tool Trace Information** - -**Used to track tool invocation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolPhoenix Tool
user_id- placed in metadata
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-#### **Tool Trace Info** - -- message_id - Message ID -- tool_name - Tool name -- start_time - Start time -- end_time - End time -- tool_inputs - Tool inputs -- tool_outputs - Tool outputs -- message_data - Message data -- error - Error information, if any -- inputs - Inputs for the message -- outputs - Outputs of the message -- tool_config - Tool configuration -- time_cost - Time cost -- tool_parameters - Tool parameters -- file_url - URL of the associated file -- Metadata - - message_id - Message ID - - tool_name - Tool name - - tool_inputs - Tool inputs - - tool_outputs - Tool outputs - - tool_config - Tool configuration - - time_cost - Time cost - - error - Error information, if any - - tool_parameters - Tool parameters - - message_file_id - Message file ID - - created_by_role - Role of the creator - - created_user_id - User ID of the creator - -**Generate Name Trace Information** - -**Used to track conversation title generation** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NamePhoenix Tool
user_id- placed in metadata
"generate_conversation_name"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["generate_name"]tags
-**Generate Name Trace Info** - -- conversation_id - Conversation ID -- inputs - Input data -- outputs - Generated conversation name -- start_time - Start time -- end_time - End time -- tenant_id - Tenant ID -- Metadata - - conversation_id - Conversation ID - - tenant_id - Tenant ID +For help evaluating the traces you collect, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/). diff --git a/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx index 716d80c59..c58441fc0 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -4,344 +4,70 @@ sidebarTitle: W&B Weave description: Send traces from Dify applications to W&B Weave for LLM observability --- - - **Prerequisites**: Dify v1.3.1 or later. - +## Connect Your App -### What is W&B Weave +Create a [W&B project](https://docs.wandb.ai/models/track/project-page#create-a-project) that your [API key](https://wandb.ai/authorize) can write to before configuring Dify. For a team project, use that team as the **Entity**. -Weights & Biases (W&B) Weave is a framework for tracking, experimenting with, evaluating, deploying, and improving LLM-based applications. Designed for flexibility and scalability, Weave supports every stage of your LLM application development workflow. +In the Dify app, open **Monitoring** > **Tracing app performance**. For **Weave**, click **Config** and enter the connection details: - - For more details, please refer to [Weave](https://docs.wandb.ai/weave). - +| Field | Required | Value | +|:------|:---------|:------| +| **API Key** | Yes | Your W&B API key. | +| **Project** | Yes | An existing, writable project. You can enter `entity/project` here and leave **Entity** blank. | +| **Entity** | No | The W&B team or user. If blank, Dify resolves the API key's default entity. | +| **Endpoint** | No | The Weave trace server. Defaults to `https://trace.wandb.ai`; HTTPS is required. | +| **Host** | No | The W&B API server. Defaults to `https://api.wandb.ai`; HTTP(S) is accepted. | -### How to Configure Weave +For a custom deployment, ask its administrator for the trace-server **Endpoint** and W&B API **Host**. Keep any path prefix they provide. -#### 1. Register/Login +Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Weave replaces the current selection. -Register/Login to [W&B Weave](https://wandb.ai/signup) and get your API key. Then, copy your API key from [here](https://wandb.ai/authorize). +Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Host** and **Endpoint** are unchanged. Re-enter them if you change either address. -#### 2. Integrate W&B Weave with Dify +## What Dify Sends -Configure Weave in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. +A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. - - ![Configure Weave in the Dify Application](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) - +For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. -After clicking configure, paste the **API Key** and **project name**, also specify the **W&B entity**(optionally, default is your username) into the configuration and save. +In Weave, open a model call to inspect its captured inputs and outputs. Available token counts appear in the call's per-model usage. Dify doesn't fill Weave's built-in cost field. - - ![Configure, Paste the API Key and Project Name, Also Specify the W&B](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) - +### Include Agent Calls and Content -Once successfully saved, you can view the monitoring status on the current page. + +Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. + - - ![Once Successfully Saved, You Can View the Monitoring Status on the Current Page](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) - +Under **Agent data capture** in the app's tracing settings: -### View Monitoring Data in Weave +- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. +- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. -Once configured, the debug or production data from applications within Dify can be monitored in Weave. + +These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. + - - ![Once Configured, the Debug or Production Data from Applications Within Dify Can](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) - +The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. -When you switch to Weave, you can view detailed operation logs of Dify applications in the dashboard. +## Verify a New Trace - - ![When You Switch to Weave, You Can View Detailed Operation Logs of Dify](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) - +1. Run a new request in your Dify app and let it finish. +2. In **Tracing app performance**, click **View** for **Weave** to open the configured project. +3. Find the new call by its run time and open it to inspect its child calls. -Detailed LLM operation logs through Weave will help you optimize the performance of your Dify application. +Traces may take time to appear after the run finishes. -### Monitoring Data List +## Troubleshooting -#### **Workflow/Chatflow Trace Information** + + + Saving checks that the project exists, is writable, and that the trace server is accessible. Confirm that Weave is selected and tracing is enabled. In Weave, open the configured entity and project. Then run the app again. -**Used to track workflows and chatflows** + Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. + + + The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. -| Workflow | Weave Trace | -| ---------------------------------------- | ---------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | placed in metadata | -| workflow_\{id\} | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | extra | -| error | error | -| workflow | tags | -| "conversation_id/none for workflow" | conversation_id in metadata | -| conversion_id | parent_run_id | - -**Workflow Trace Info** - -* workflow_id - Unique identifier of the workflow -* conversation_id - Conversation ID -* workflow_run_id - ID of the current run -* tenant_id - Tenant ID -* elapsed_time - Time taken for the current run -* status - Run status -* version - Workflow version -* total_tokens - Total tokens used in the current run -* file_list - List of processed files -* triggered_from - Source that triggered the current run -* workflow_run_inputs - Input data for the current run -* workflow_run_outputs - Output data for the current run -* error - Errors encountered during the current run -* query - Query used during the run -* workflow_app_log_id - Workflow application log ID -* message_id - Associated message ID -* start_time - Start time of the run -* end_time - End time of the run -* workflow node executions - Information about workflow node executions -* Metadata - * workflow_id - Unique identifier of the workflow - * conversation_id - Conversation ID - * workflow_run_id - ID of the current run - * tenant_id - Tenant ID - * elapsed_time - Time taken for the current run - * status - Run status - * version - Workflow version - * total_tokens - Total tokens used in the current run - * file_list - List of processed files - * triggered_from - Source that triggered the current run - -#### **Message Trace Information** - -**Used to track LLM-related conversations** - -| Chat | Weave Trace | -| -------------------------------- | ---------------------------- | -| message_id | id | -| user_session_id | placed in metadata | -| "message_\{id\}" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | extra | -| error | error | -| "message", conversation_mode | tags | -| conversation_id | conversation_id in metadata | -| conversion_id | parent_run_id | - -**Message Trace Info** - -* message_id - Message ID -* message_data - Message data -* user_session_id - User session ID -* conversation_model - Conversation mode -* message_tokens - Number of tokens in the message -* answer_tokens - Number of tokens in the answer -* total_tokens - Total number of tokens in the message and answer -* error - Error information -* inputs - Input data -* outputs - Output data -* file_list - List of processed files -* start_time - Start time -* end_time - End time -* message_file_data - File data associated with the message -* conversation_mode - Conversation mode -* Metadata - * conversation_id - Conversation ID - * ls_provider - Model provider - * ls_model_name - Model ID - * status - Message status - * from_end_user_id - ID of the sending user - * from_account_id - ID of the sending account - * agent_based - Whether the message is agent-based - * workflow_run_id - Workflow run ID - * from_source - Message source - -#### **Moderation Trace Information** - -**Used to track conversation moderation** - -| Moderation | Weave Trace | -| ------------- | -------------------- | -| user_id | placed in metadata | -| “moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| moderation | tags | -| message_id | parent_run_id | - -**Moderation Trace Info** - -* message_id - Message ID -* user_id: User ID -* workflow_app_log_id - Workflow application log ID -* inputs - Moderation input data -* message_data - Message data -* flagged - Whether the content is flagged for attention -* action - Specific actions taken -* preset_response - Preset response -* start_time - Moderation start time -* end_time - Moderation end time -* Metadata - * message_id - Message ID - * action - Specific actions taken - * preset_response - Preset response - -#### **Suggested Question Trace Information** - -**Used to track suggested questions** - -| Suggested Question | Weave Trace | -| ---------------------- | -------------------- | -| user_id | placed in metadata | -| suggested_question | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| suggested_question | tags | -| message_id | parent_run_id | - -**Message Trace Info** - -* message_id - Message ID -* message_data - Message data -* inputs - Input content -* outputs - Output content -* start_time - Start time -* end_time - End time -* total_tokens - Number of tokens -* status - Message status -* error - Error information -* from_account_id - ID of the sending account -* agent_based - Whether the message is agent-based -* from_source - Message source -* model_provider - Model provider -* model_id - Model ID -* suggested_question - Suggested question -* level - Status level -* status_message - Status message -* Metadata - * message_id - Message ID - * ls_provider - Model provider - * ls_model_name - Model ID - * status - Message status - * from_end_user_id - ID of the sending user - * from_account_id - ID of the sending account - * workflow_run_id - Workflow run ID - * from_source - Message source - -#### **Dataset Retrieval Trace Information** - -**Used to track knowledge base retrieval** - -| Dataset Retrieval | Weave Trace | -| --------------------- | -------------------- | -| user_id | placed in metadata | -| dataset_retrieval | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| dataset_retrieval | tags | -| message_id | parent_run_id | - -**Dataset Retrieval Trace Info** - -* message_id - Message ID -* inputs - Input content -* documents - Document data -* start_time - Start time -* end_time - End time -* message_data - Message data -* Metadata - * message_id - Message ID - * ls_provider - Model provider - * ls_model_name - Model ID - * status - Message status - * from_end_user_id - ID of the sending user - * from_account_id - ID of the sending account - * agent_based - Whether the message is agent-based - * workflow_run_id - Workflow run ID - * from_source - Message source - -#### **Tool Trace Information** - -**Used to track tool invocation** - -| Tool | Weave Trace | -| --------------------- | -------------------- | -| user_id | placed in metadata | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| "tool", tool_name | tags | -| message_id | parent_run_id | - -#### **Tool Trace Info** - -* message_id - Message ID -* tool_name - Tool name -* start_time - Start time -* end_time - End time -* tool_inputs - Tool inputs -* tool_outputs - Tool outputs -* message_data - Message data -* error - Error information, if any -* inputs - Inputs for the message -* outputs - Outputs of the message -* tool_config - Tool configuration -* time_cost - Time cost -* tool_parameters - Tool parameters -* file_url - URL of the associated file -* Metadata - * message_id - Message ID - * tool_name - Tool name - * tool_inputs - Tool inputs - * tool_outputs - Tool outputs - * tool_config - Tool configuration - * time_cost - Time cost - * error - Error information, if any - * tool_parameters - Tool parameters - * message_file_id - Message file ID - * created_by_role - Role of the creator - * created_user_id - User ID of the creator - -**Generate Name Trace Information** - -**Used to track conversation title generation** - -| Generate Name | Weave Trace | -| ----------------- | -------------------- | -| user_id | placed in metadata | -| generate_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| generate_name | tags | - -**Generate Name Trace Info** - -* conversation_id - Conversation ID -* inputs - Input data -* outputs - Generated conversation name -* start_time - Start time -* end_time - End time -* tenant_id - Tenant ID -* Metadata - * conversation_id - Conversation ID - * tenant_id - Tenant ID + For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. + + diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index 4991de9b8..c19a6480d 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -1,393 +1,82 @@ --- title: Alibaba Cloud Monitor の統合 +sidebarTitle: Alibaba Cloud Monitor +description: Dify のトレースを OpenTelemetry 経由で Alibaba Cloud Monitor（ARMS）に送信します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-aliyun) を参照してください。 -## Alibaba Cloud Monitor とは +## アプリの接続 -Alibaba Cloud は、Dify アプリケーションのワンクリック監視、トレース、評価を可能にする、フルマネージドかつメンテナンス不要のオブザーバビリティプラットフォームを提供します。 +[Alibaba Cloud の接続手順](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin) に沿って、デプロイ先の管理者に License Key と HTTP トレース URL を確認します。Dify の各サービスから接続できるリージョンとネットワークアドレスを選んでもらってください。 - - Alibaba Cloud Monitor は、[LoongSuite](https://github.com/alibaba/loongsuite-python-agent) エージェントやオープンソースの OpenTelemetry エージェントを通じて、Python/Golang/Java アプリケーションをネイティブにサポートします。Dify LLM アプリケーションのワンクリック監視に加え、非侵入型エージェントによる Dify コンポーネントおよびその上下流依存関係のエンドツーエンドの可観測性もサポートします。 - - 詳細は [Cloud Monitor ドキュメント](https://www.alibabacloud.com/help/en/cms/cloudmonitor-1-0/product-overview/what-is-cloudmonitor?spm=a3c0i.63551.2277339270.1.76c7112eeKEvSr) をご参照ください。 - +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**クラウドモニター** の **設定** をクリックし、接続情報を入力してください。 -## Alibaba Cloud Monitor の設定方法 +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **License Key** | はい | コレクタの認証キー。エンドポイントとは別に入力します。 | +| **Endpoint** | はい | コレクタの HTTP(S) ベース URL。ポートを明示的に指定できます。 | +| **App Name** | はい | ARMS コンソールに表示するアプリケーション名。任意の名前を指定します。 | -### 1. Alibaba Cloud のエンドポイントとライセンスキーの取得 +HTTP トレース URL の `/adapt_` より前の部分を **Endpoint** に入力します。認証用の API トークンは **License Key** に入力してください。たとえば、次の URL では以下のように指定します。 -1. [ARMS コンソール](https://account.alibabacloud.com/login/login.htm?spm=5176.12901015-2.0.0.68d74b84XRatpU)にログインし、左側のナビゲーションバーで **Integration Center** をクリックします。 -2. **Server-side Applications** エリアで **OpenTelemetry** カードをクリックします。 -3. 表示された **OpenTelemetry** パネルで、エクスポートプロトコルとして **gRPC** を選択し、実際のデプロイに応じて接続方法とリージョンを選択します。 +```text +https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces +``` - - ![Alibaba Cloud アクセスポイントの取得](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/get_endpoint.png) - +- **Endpoint**: `https://tracing-analysis-dc-hz.aliyuncs.com` +- **License Key**: `example-key` -4. **Public Endpoint** と **Authentication Token (License Key)** を保存します。 +HTTP エンドポイントにポートが含まれている場合は、そのまま指定してください。`8090` などの gRPC ポートは使用できません。 - - エンドポイントにはポート番号が含まれていません（例：`http://tracing-cn-heyuan.arms.aliyun.com`）。 - - -### 2. Dify で Cloud Monitor を設定 - - - Dify v1.6.0 以上が必要です。 - - -1. Dify コンソールにログインし、監視したいアプリケーションに移動します。 -2. 左側のナビゲーションバーで **Monitoring** を開きます。 -3. **Tracing app performance** をクリックし、**Cloud Monitor** エリアで **Configure** をクリックします。 - - - ![Alibaba Cloud Monitor の設定](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/config_cms.png) - - -4. 表示されたダイアログで、手順 1 で取得した **License Key** と **Endpoint** を入力し、**App Name**（ARMS コンソールに表示されるアプリケーション名）をカスタマイズして **Save & Enable** をクリックします。 - -## Alibaba Cloud Monitor での監視データの表示 - -設定後、Dify のアプリケーションからのデバッグまたは本番データは Cloud Monitor で監視できます。 - -### 方法 1: Dify アプリケーションから ARMS コンソールにジャンプ +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Cloud Monitor を選ぶと、現在の選択が置き換わります。 -Dify コンソールでトレースが有効になっているアプリケーションを選択し、**Tracing Configuration** に移動して、**Cloud Monitor** エリアの **View** をクリックします。 +保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 -### 方法 2: ARMS コンソールで直接表示 +## Dify が送信するデータ -ARMS コンソールの **LLM Application Monitoring > Application List** ページで、対応する Dify アプリケーションに移動します。 +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 -## より多くのデータにアクセス +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 -Cloud Monitor は、Dify クラスターのさまざまなコンポーネントにアクセスしてエンドツーエンドのトレースを実現するマルチランゲージの非侵入型エージェントを提供します。 +Alibaba Cloud Monitor でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify はこのプラットフォームに標準で用意されている費用フィールドには値を設定しません。 -| Dify コンポーネント | エージェント | 詳細 | -|----------------|-------|---------| -| Nginx | OpenTelemetry Agent | [Nginx トレースに OpenTelemetry を使用](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx?spm=a2c63.l28256.help-menu-search-90275.d_1) | -| API | LoongSuite-Python Agent | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | -| Sandbox | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -| Worker | OpenTelemetry Agent | [OpenTelemetry を介して Python アプリケーションデータを送信](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications?spm=a2c63.p38356.help-menu-90275.d_2_0_5_0.18ee53a4EGoGuS) | -| Plugin-Daemon | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | +### Agent の呼び出しと内容の収集 -## 監視データリスト - -Cloud Monitor は、Dify の Workflow/Chatflow/Chat/Agent アプリケーションからデータを収集することをサポートしており、ワークフローおよびワークフローノードの実行詳細、モデル呼び出し、ツール呼び出し、知識取得、さまざまなプロセスノードの実行詳細、会話やユーザー情報などのメタデータをカバーしています。 - -### Workflow/Chatflow トレース情報 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowAlibaba Cloud Monitor Trace
workflow\_idワークフローの一意の識別子
conversation\_id会話 ID
workflow\_run\_idこの実行の ID
tenant\_idテナント ID
elapsed\_timeこの実行の所要時間
status実行ステータス
versionワークフローのバージョン
total\_tokensこの実行で使用されたトークンの総数
file\_list処理されたファイルのリスト
triggered\_fromこの実行をトリガーしたソース
workflow\_run\_inputsこの実行の入力データ
workflow\_run\_outputsこの実行の出力データ
errorこの実行中に発生したエラー
query実行時に使用されたクエリ
workflow\_app\_log\_idWorkflow アプリケーションログ ID
message\_id関連するメッセージ ID
start\_time実行開始時刻
end\_time実行終了時刻
- -**ワークフロートレースメタデータ** - -* workflow\_id - ワークフローの一意の識別子 -* conversation\_id - 会話 ID -* workflow\_run\_id - この実行の ID -* tenant\_id - テナント ID -* elapsed\_time - この実行の所要時間 -* status - 実行ステータス -* version - ワークフローのバージョン -* total\_tokens - この実行で使用されたトークンの総数 -* file\_list - 処理されたファイルのリスト -* triggered\_from - トリガーソース - -### メッセージトレース情報 + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MessageAlibaba Cloud Monitor Trace
message\_idメッセージ ID
message\_dataメッセージデータ
user\_session\_idユーザーの session\_id
conversation\_model会話モデル
message\_tokensメッセージ内のトークン数
answer\_tokens回答内のトークン数
total\_tokensメッセージと回答のトークンの総数
errorエラー情報
inputs入力データ
outputs出力データ
file\_list処理されたファイルのリスト
start\_time開始時刻
end\_time終了時刻
message\_file\_dataメッセージに関連するファイルデータ
conversation\_mode会話モード
+アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 -**メッセージトレースメタデータ** +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -* conversation\_id - メッセージが属する会話の ID -* ls\_provider - モデルプロバイダー -* ls\_model\_name - モデル ID -* status - メッセージステータス -* from\_end\_user\_id - 送信ユーザーの ID -* from\_account\_id - 送信アカウントの ID -* agent\_based - エージェントベースかどうか -* workflow\_run\_id - ワークフロー実行 ID -* from\_source - メッセージソース -* message\_id - メッセージ ID + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + -### データセット取得トレース情報 +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalAlibaba Cloud Monitor Trace
message\_idメッセージ ID
inputs入力コンテンツ
documentsドキュメントデータ
start\_time開始時刻
end\_time終了時刻
message\_dataメッセージデータ
+## 新しいトレースの確認 -**データセット取得トレースメタデータ** +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**クラウドモニター** の **見る** をクリックして ARMS LLM コンソールを開きます。 +3. 入力したアプリケーション名を探します。実行時刻を手がかりに新しいトレースを見つけ、子のスパンを確認します。 -* message\_id - メッセージ ID -* ls\_provider - モデルプロバイダー -* ls\_model\_name - モデル ID -* status - メッセージステータス -* from\_end\_user\_id - 送信ユーザーの ID -* from\_account\_id - 送信アカウントの ID -* agent\_based - エージェントベースかどうか -* workflow\_run\_id - ワークフロー実行 ID -* from\_source - メッセージソース +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 -### ツールトレース情報 +## トラブルシューティング - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolAlibaba Cloud Monitor Trace
message\_idメッセージ ID
tool\_nameツール名
start\_time開始時刻
end\_time終了時刻
tool\_inputsツール入力
tool\_outputsツール出力
message\_dataメッセージデータ
errorエラー情報（該当する場合）
inputsメッセージの入力コンテンツ
outputsメッセージの回答コンテンツ
tool\_configツール設定
time\_costコスト時間
tool\_parametersツールパラメータ
file\_url関連ファイルの URL
+ + + 保存時にはコレクタへのアクセスをテストしますが、実際のトレースは作成しません。Cloud Monitor が選択され、トレースが有効になっていることを確認してください。Alibaba Cloud Monitor で、Dify に設定した名前のアプリケーションを開き、アプリを再度実行します。 -**ツールトレースメタデータ** + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 -* message\_id - メッセージ ID -* tool\_name - ツール名 -* tool\_inputs - ツール入力 -* tool\_outputs - ツール出力 -* tool\_config - ツール設定 -* time\_cost - コスト時間 -* error - エラー情報 -* tool\_parameters - ツールパラメータ -* message\_file\_id - メッセージファイル ID -* created\_by\_role - 作成者の役割 -* created\_user\_id - 作成者のユーザーID \ No newline at end of file + プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx index 87b56bf71..00d53adc2 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,519 +1,74 @@ --- title: Arize の統合 +sidebarTitle: Arize +description: Dify アプリを Arize に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-arize) を参照してください。 +## アプリの接続 -### 1 Arize とは +Arize の **Settings** > **API Keys** で、API キーと現在の Space ID を取得します。詳細は [Arize クイックスタート](https://arize.com/docs/ax/quickstarts) を参照してください。送信先のプロジェクト名を決めておきます。Phoenix に接続する場合は、[Phoenix 連携](/ja/self-host/use-dify/monitor/integrations/integrate-phoenix) の手順に従ってください。 -[Arize AX](https://arize.com/products/ax/) は、[Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host) が提供するフル機能プラットフォームです。LLM やエージェント駆動型アプリケーションの可観測性、オンライン・オフライン評価、モニタリング、実験に対応します。本番運用チームや AI ネイティブ企業、エンタープライズ向けに設計されており、マネージドクラウドまたはエンタープライズ向けセルフホストでデプロイできます。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Arize** の **設定** をクリックし、接続情報を入力してください。 -ローカル開発や実験、単一コンテナでのセルフホストに適したオープンソース構成が必要な場合は、代わりに [Phoenix 統合](/ja/self-host/use-dify/monitor/integrations/integrate-phoenix) を設定してください。 +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **API Key** | はい | データ取り込み権限を持つ Arize API キー。 | +| **Space ID** | はい | トレースの送信先となる Arize スペース。 | +| **プロジェクト** | はい | 送信先のプロジェクト名。 | +| **Endpoint** | いいえ | 既定値は `https://otlp.arize.com`。独自のコレクタには、管理者が指定するアドレスを使用します。 | -トレースの送信が始まったら、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。障害のデバッグ、エージェント動作の評価、モデル品質のモニタリングにトレースを活用する方法を確認できます。 +独自の **Endpoint** は OTLP/gRPC に対応している必要があります。ホスト名とポートを管理者に確認してください。`/v1/traces` などの HTTP パスは含めません。 -### 2 Arize の使い方 +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Arize を選ぶと、現在の選択が置き換わります。 -#### 1. Arize の[公式サイト](https://app.arize.com/auth/join)から登録し、ログインする。 +保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、**API Key** と **Space ID** を空欄にすると保存済みの値を維持できます。エンドポイントを変更した場合は、両方を再入力してください。 -### 2. Arize API キーの取得 +## Dify が送信するデータ -右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 - - ![Arize API キー](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) - +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 -### 3. Arize と Dify を統合 +Arize でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify は Arize に標準で用意されている費用フィールドには値を設定しません。 -Dify アプリケーションで Arize を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 +### Agent の呼び出しと内容の収集 - - ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) - + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + -設定後、Arize で作成した **API Key**, **Space ID** と **プロジェクト名** を設定ページに貼り付けて保存します。 +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 - - ![Arize の設定](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) - +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -保存に成功すると、現在のページで監視ステータスを確認できます。 + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + - - ![Arize の設定](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) - +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 -## モニタリングデータリスト +## 新しいトレースの確認 -### **ワークフロー/会話フロートラッキング情報** +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**Arize** の **見る** をクリックします。ショートカットが使えない場合は、Arize のスペースとプロジェクトを直接開きます。 +3. 実行時刻を手がかりに新しいトレースを探し、開いて子のスパンを確認します。 -**ワークフローと会話フローの追跡に使用** +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ワークフローArize トラッキング
workflow_app_log_id/workflow_run_idid
user_session_id- メタデータに配置
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**ワークフロートラッキング情報** +## トラブルシューティング -- workflow_id - ワークフローの一意識別子 -- conversation_id - 会話 ID -- workflow_run_id - 現在の実行 ID -- tenant_id - テナント ID -- elapsed_time - 現在の実行にかかった時間 -- status - 実行ステータス -- version - ワークフローバージョン -- total_tokens - 現在の実行で使用されたトークン総数 -- file_list - 処理されたファイルのリスト -- triggered_from - 実行をトリガーしたソース -- workflow_run_inputs - 現在の実行の入力データ -- workflow_run_outputs - 現在の実行の出力データ -- error - 実行中に発生したエラー -- query - 実行中に使用されたクエリ -- workflow_app_log_id - Workflow アプリケーションログ ID -- message_id - 関連するメッセージ ID -- start_time - 実行開始時間 -- end_time - 実行終了時間 -- workflow node executions - ワークフローノードの実行情報 -- メタデータ - - workflow_id - ワークフローの一意識別子 - - conversation_id - 会話 ID - - workflow_run_id - 現在の実行 ID - - tenant_id - テナント ID - - elapsed_time - 現在の実行にかかった時間 - - status - 実行ステータス - - version - ワークフローバージョン - - total_tokens - 現在の実行で使用されたトークン総数 - - file_list - 処理されたファイルのリスト - - triggered_from - 実行をトリガーしたソース + + + 保存時にはコレクタへのアクセスをテストしますが、実際のトレースは作成しません。Arize が選択され、トレースが有効になっていることを確認してください。Arize で、Dify に設定したスペースとプロジェクトを開き、アプリを再度実行します。 ---- - -### **メッセージトラッキング情報** - -**LLM 関連の会話を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
チャットArize LLM
message_idid
user_session_id- メタデータに配置
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**メッセージトラッキング情報** - -- message_id - メッセージ ID -- message_data - メッセージデータ -- user_session_id - ユーザーセッション ID -- conversation_model - 会話モード -- message_tokens - メッセージ内のトークン数 -- answer_tokens - 回答内のトークン数 -- total_tokens - メッセージと回答のトークン総数 -- error - エラー情報 -- inputs - 入力データ -- outputs - 出力データ -- file_list - 処理されたファイルリスト -- start_time - 開始時間 -- end_time - 終了時間 -- message_file_data - メッセージ関連のファイルデータ -- conversation_mode - 会話モード -- メタデータ - - conversation_id - 会話 ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージソース - -### **レビュー追跡情報** - -**会話のレビューを追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
レビューArize Tool
user_id- メタデータに配置
"moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**レビュー追跡情報** - -- message_id - メッセージ ID -- user_id - ユーザーID -- workflow_app_log_id - Workflow アプリケーションログ ID -- inputs - レビュー入力データ -- message_data - メッセージデータ -- flagged - 注意が必要とマークされたかどうか -- action - 実施された具体的なアクション -- preset_response - プリセットレスポンス -- start_time - レビュー開始時間 -- end_time - レビュー終了時間 -- メタデータ - - message_id - メッセージ ID - - action - 実施されたアクション - - preset_response - プリセットレスポンス - ---- - -### **提案質問追跡情報** - -**提案質問を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
提案質問Arize LLM
user_id- メタデータに配置
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**提案質問追跡情報** - -- message_id - メッセージ ID -- message_data - メッセージデータ -- inputs - 入力データ -- outputs - 出力データ -- start_time - 開始時間 -- end_time - 終了時間 -- total_tokens - トークン総数 -- status - メッセージステータス -- error - エラー情報 -- from_account_id - 送信アカウント ID -- agent_based - エージェントベースかどうか -- from_source - メッセージの送信元 -- model_provider - モデルプロバイダー -- model_id - モデル ID -- suggested_question - 提案された質問 -- level - ステータスレベル -- status_message - ステータスメッセージ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- - -### **データセット検索追跡情報** - -**ナレッジベース検索を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
データセット検索Arize Retriever
user_id- メタデータに配置
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**データセット検索追跡情報** - -- message_id - メッセージ ID -- inputs - 入力データ -- documents - ドキュメントデータ -- start_time - 開始時間 -- end_time - 終了時間 -- message_data - メッセージデータ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- - -### **ツール追跡情報** - -**ツールの呼び出しを追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ツールArize Tool
user_id- メタデータに配置
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-**ツール追跡情報** + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから gRPC コレクタに接続できる必要があります。管理者にホスト名、ポート、ネットワークアクセスの確認を依頼してください。`localhost` などのループバックアドレスは使用できません。到達可能なサーバーアドレスを指定してください。 + + -- message_id - メッセージ ID -- tool_name - ツール名 -- start_time - 開始時間 -- end_time - 終了時間 -- tool_inputs - ツール入力 -- tool_outputs - ツール出力 -- message_data - メッセージデータ -- error - エラー情報（該当する場合） -- inputs - メッセージの入力 -- outputs - メッセージの出力 -- tool_config - ツール設定 -- time_cost - 時間コスト -- tool_parameters - ツールパラメーター -- file_url - 関連するファイルの URL -- メタデータ - - message_id - メッセージ ID - - tool_name - ツール名 - - tool_inputs - ツール入力 - - tool_outputs - ツール出力 - - tool_config - ツール設定 - - time_cost - 時間コスト - - error - エラー情報（該当する場合） - - tool_parameters - ツールパラメーター - - message_file_id - メッセージファイル ID - - created_by_role - 作成者の役割 - - created_user_id - 作成者ユーザーID +収集したトレースの評価方法については、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。 diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index 1459067dd..bfa7881f8 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,642 +1,77 @@ --- title: Langfuse の統合 +sidebarTitle: Langfuse +description: Dify アプリを Langfuse に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-langfuse) を参照してください。 +## アプリの接続 -### Langfuse とは +Langfuse でプロジェクトを作成し、**Project Settings** > **API Keys** から [API キー](https://langfuse.com/faq/all/where-are-langfuse-api-keys) を取得します。Langfuse Cloud では、利用する [リージョンのベース URL](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url) を選び、末尾の `/api/public` を除きます。セルフホストの場合は、管理者にベース URL を確認してください。 -Langfuse は、チームがアプリケーションのデバッグ、分析、反復作業を協力して行うことができる、オープンソースの大規模言語モデル（LLM）エンジニアリングプラットフォームです。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Langfuse** の **設定** をクリックし、接続情報を入力してください。 - - Langfuse の紹介： [https://langfuse.com/](https://langfuse.com/) - +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **秘密キー** | はい | プロジェクトの秘密キー。 | +| **公開キー** | はい | 対応する公開キー。 | +| **Host** | はい | Langfuse インスタンスの HTTP(S) ベース URL。 | -### Langfuse の設定方法 + +この連携では、Langfuse の従来の取り込み API、`/api/public/ingestion` でトレースデータを受信します。`events_only` モードの Langfuse v4 では、このトレースを受信できません。接続前に、Langfuse の管理者と [取り込み API の互換性](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api) を確認してください。 + -1. [公式ウェブサイト](https://langfuse.com/)で Langfuse に登録し、ログインします。 -2. Langfuse でプロジェクトを作成します。ログイン後、ホームページで **新規** をクリックして自身のプロジェクトを作成します。この **プロジェクト** は、Dify の **アプリケーション** と関連付けてデータを監視するために使用されます。 +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Langfuse を選ぶと、現在の選択が置き換わります。 - - ![Langfuse でプロジェクトを作成します](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) - +保存済みの認証情報は、編集時には表示されません。**Host** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 -プロジェクトの名前を編集してください。 +## Dify が送信するデータ - - ![Langfuse でプロジェクトを作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) - +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 -3. プロジェクト API 資格情報を作成します。プロジェクトの左サイドバーで **設定** をクリックし、設定を開きます。 +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 - - ![プロジェクトの API 認証情報を作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) - +Langfuse で生成の記録を開くと、モデル呼び出しで収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 -設定で **API キーを作成** をクリックして、プロジェクトの API 資格情報を作成します。 +### Agent の呼び出しと内容の収集 - - ![プロジェクトの API 認証情報を作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) - + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + -**シークレットキー**、**パブリックキー**、**ホスト**をコピーして保存します。 +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 - - ![API キー設定を取得](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) - +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -4. Dify で Langfuse を設定します。監視が必要なアプリケーションを開き、サイドメニューで **モニタリング** を開き、ページ上で **アプリパフォーマンスのトレース** を選択します。 + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + - - ![Langfuse を設定](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) - +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 -設定をクリックした後、Langfuse で作成した **シークレットキー、パブリックキー、ホスト** を構成に貼り付けて保存します。 +## 新しいトレースの確認 - - ![Langfuse を設定](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) - +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**Langfuse** の **見る** をクリックして設定したプロジェクトを開きます。 +3. 実行時刻を手がかりに新しいトレースを探します。開いてモデルの生成やノードのスパンを確認します。 -正常に保存されると、現在のページで状態を確認できます。開始と表示されている場合、監視が行われています。 +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 - - ![構成ステータスを表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) - +## トラブルシューティング -### Langfuse での監視データの閲覧 + + + 設定の保存時にはプロジェクトへのアクセスを確認します。Langfuse が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、同じプロジェクトを確認します。 -設定後、Dify のアプリケーションのデバッグまたはプロダクションデータを Langfuse で見ることができます。 + 管理者に、ワーカーログの取り込みエラーを調べてもらってください。Langfuse が `/api/public/ingestion` 経由でデータを受信できることも確認します。新しい実行がまだ表示されない場合は、[トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) も確認してもらってください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 - - ![](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) - + プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + - - ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) - - -### 監視データの一覧 - -#### Workflow と Chatflow の情報をトレースする - -**Workflow と Chatflow のトレース** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ワークフローLangFuse Trace
workflow\_app\_log\_id/workflow\_run\_idid
user\_session\_iduser\_id
{"workflow_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
モデルトークン消費量usage
元データmetadata
errorlevel
errorstatus\_message
\[workflow]tags
\["message", conversation\_mode]session\_id
conversion\_idparent\_observation\_id
-**ワークフロートレース情報** - -* workflow\_id - ワークフローのユニーク ID -* conversation\_id - 会話 ID -* workflow\_run\_id - このランタイムのワークフローID -* tenant\_id - テナント ID -* elapsed\_time - このランタイムの経過時間 -* status - ランタイムのステータス -* version - ワークフローのバージョン -* total\_tokens - このランタイムで使用されたトークンの総数 -* file\_list - 処理されたファイルのリスト -* triggered\_from - このランタイムをトリガーしたソース -* workflow\_run\_inputs - このワークフローの入力 -* workflow\_run\_outputs - このワークフローの出力 -* error - エラーメッセージ -* query - ランタイムで使用されたクエリ -* workflow\_app\_log\_id - Workflow アプリケーションログ ID -* message\_id - 関連するメッセージ ID -* start\_time - このランタイムの開始時間 -* end\_time - このランタイムの終了時間 -* ワークフローノード実行 - ワークフローノードのランタイム情報 -* 元データ（Metadata） - * workflow\_id - ワークフローのユニーク ID - * conversation\_id - 会話 ID - * workflow\_run\_id - このランタイムのワークフローID - * tenant\_id - テナント ID - * elapsed\_time - このランタイムの経過時間 - * status - オペレーション状態 - * version - ワークフローのバージョン - * total\_tokens - このランタイムで使用されたトークンの総数 - * file\_list - 処理されたファイルのリスト - * triggered\_from - このランタイムをトリガーしたソース - -#### メッセージトレース情報 - -**LLM 会話をトレースするために** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
メッセージLangFuse Generation/Trace
message\_idid
user\_session\_iduser\_id
{"message_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
モデルトークン消費量usage
元データmetadata
errorlevel
errorstatus\_message
\["message", conversation\_mode]tags
conversation\_idsession\_id
conversion\_idparent\_observation\_id
-**メッセージトレース情報** - -* message\_id - メッセージ ID -* message\_data - メッセージデータ -* user\_session\_id - ユーザーのセッション ID -* conversation\_model - 会話モデル -* message\_tokens - メッセージトークン -* answer\_tokens - 回答トークン -* total\_tokens - メッセージと回答からの総トークン -* error - エラーメッセージ -* inputs - 入力データ -* outputs - 出力データ -* file\_list - 処理されたファイルのリスト -* start\_time - 開始時間 -* end\_time - 終了時間 -* message\_file\_data - 関連するファイルデータのメッセージ -* conversation\_mode - 会話モード -* 元データ（Metadata） - * conversation\_id - 会話 ID - * ls\_provider - モデルプロバイダー - * ls\_model\_name - モデル ID - * status - メッセージのステータス - * from\_end\_user\_id - 送信ユーザーの ID - * from\_account\_id - 送信アカウントの ID - * agent\_based - エージェントベースかどうか - * workflow\_run\_id - このランタイムのワークフローID - * from\_source - メッセージソース - -#### モデレーショントレース情報 - -**会話のモデレーションを追跡するために使用されます** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
モデレーションLangFuse Generation/Trace
user\_iduser\_id
moderationname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
元データmetadata
\[moderation]tags
message\_idparent\_observation\_id
-**メッセージトレース情報** - -* message\_id - メッセージ ID -* user\_id - ユーザーID -* workflow\_app\_log\_id workflow\_app\_log\_id -* inputs - レビューのための入力データ -* message\_data - メッセージデータ -* flagged - 注目のためにフラグが立てられているかどうか -* action - 実施すべき具体的なアクション -* preset\_response - プリセット応答 -* start\_time - レビューの開始時間 -* end\_time - レビューの終了時間 -* 元データ（Metadata） - * message\_id - メッセージ ID - * action - 実施すべき具体的なアクション - * preset\_response - プリセット応答 - -#### 推奨質問のトレース情報 - -**推奨質問を追跡するために使用されます** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
推奨質問LangFuse Generation/Trace
user\_iduser\_id
suggested\_questionname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
元データmetadata
\[suggested\_question]tags
message\_idparent\_observation\_id
-**メッセージトレース情報** - -* message\_id - メッセージ ID -* message\_data - メッセージデータ -* inputs - 入力データ -* outputs - 出力データ -* start\_time - 開始時間 -* end\_time - 終了時間 -* total\_tokens - 総トークン数 -* status - メッセージのステータス -* error - エラーメッセージ -* from\_account\_id - 送信アカウント ID -* agent\_based - エージェントベースかどうか -* from\_source - メッセージソース -* model\_provider - モデルプロバイダー -* model\_id - モデル ID -* suggested\_question - 推奨質問 -* level - ステータスレベル -* status\_message - メッセージステータス -* 元データ（Metadata） - * message\_id - メッセージ ID - * ls\_provider - モデルプロバイダー - * ls\_model\_name - モデル ID - * status - メッセージのステータス - * from\_end\_user\_id - 送信ユーザーの ID - * from\_account\_id - 送信アカウント ID - * workflow\_run\_id - このランタイムのワークフローID - * from\_source - メッセージソース - -#### データセットリトリーバルトレース情報 - -**知識ベースの検索を追跡するために使用されます** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
データセットリトリーバルLangFuse Generation/Trace
user\_iduser\_id
dataset\_retrievalname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
元データmetadata
\[dataset\_retrieval]tags
message\_idparent\_observation\_id
-**データセットリトリーバルトレース情報** - -* message\_id - メッセージ ID -* inputs - 入力メッセージ -* documents - ドキュメントデータ -* start\_time - 開始時間 -* end\_time - 終了時間 -* message\_data - メッセージデータ -* 元データ（Metadata） - * message\_id - メッセージ ID - * ls\_provider - モデルプロバイダー - * ls\_model\_name - モデル ID - * status - モデルのステータス - * from\_end\_user\_id - 送信ユーザーの ID - * from\_account\_id - 送信アカウントの ID - * agent\_based - エージェントベースかどうか - * workflow\_run\_id - このランタイムのワークフローID - * from\_source - メッセージソース - -#### ツールトレース情報 - -**ツール呼び出しを追跡するために使用されます** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ツールLangFuse Generation/Trace
user\_iduser\_id
tool\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
元データmetadata
\["tool", tool\_name]tags
message\_idparent\_observation\_id
-**ツールトレース情報** - -* message\_id - メッセージ ID -* tool\_name - ツール名 -* start\_time - 開始時間 -* end\_time - 終了時間 -* tool\_inputs - ツール入力 -* tool\_outputs - ツール出力 -* message\_data - メッセージデータ -* error - エラーメッセージが存在する場合 -* inputs - メッセージの入力 -* outputs - メッセージの出力 -* tool\_config - ツール構成 -* time\_cost - 時間コスト -* tool\_parameters - ツールパラメータ -* file\_url - 関連ファイルの URL -* 元データ（Metadata） - * message\_id - メッセージ ID - * tool\_name - ツール名 - * tool\_inputs - ツール入力 - * tool\_outputs - ツール出力 - * tool\_config - ツール構成 - * time\_cost - 時間コスト - * error - エラーメッセージ - * tool\_parameters - ツールパラメータ - * message\_file\_id - メッセージファイル ID - * created\_by\_role - 作成者の役割 - * created\_user\_id - 作成したユーザーID - -#### 名前生成トレース - -**会話タイトルの生成を追跡するために使用されます** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
名前生成LangFuse Generation/Trace
user\_iduser\_id
generate\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
元データmetadata
\[generate\_name]tags
-**名前生成トレース情報** - -* conversation\_id - 会話 ID -* inputs - 入力データ -* outputs - 生成されたセッション名 -* start\_time - 開始時間 -* end\_time - 終了時間 -* tenant\_id - テナント ID -* 元データ（Metadata） - * conversation\_id - 会話 ID - * tenant\_id - テナント ID - -### Langfuse プロンプト管理 - -[Langfuse プロンプト管理プラグイン](https://github.com/gao-ai-com/dify-plugin-langfuse)（コミュニティによって維持されている）は、Dify アプリケーションで[Langfuse で管理およびバージョン管理されているプロンプト](https://langfuse.com/docs/prompt-management/get-started)を使用できるようにし、大規模言語モデル（LLM）アプリケーション開発のワークフローを向上させます。主な機能は以下の通りです： - -- **プロンプトを取得する**：Langfuse で管理されている特定のプロンプトを取得します。 -- **プロンプトを検索する**：Langfuse でさまざまなフィルターを使用してプロンプトを検索します。 -- **プロンプトを更新する**：Langfuse でプロンプトの新しいバージョンを作成し、タグ/ラベルを設定します。 - -この統合により、プロンプトの管理およびバージョン管理のプロセスが合理化され、より効率的な開発と反復サイクルに寄与します。プラグインとインストール手順は[こちら](https://github.com/gao-ai-com/dify-plugin-langfuse)で見つけることができます。 +Langfuse で管理するプロンプトを利用するには、[Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) を参照してください。コミュニティが保守するプラグインで、リンク先にインストール方法と使い方があります。 diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index 60b12f7e8..2d300c4b4 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,368 +1,73 @@ --- title: LangSmith の統合 +sidebarTitle: LangSmith +description: Dify アプリを LangSmith に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-langsmith) を参照してください。 +## アプリの接続 -### 1 LangSmith とは +対象のワークスペースでプロジェクトを読み取り、トレースを送信できる [LangSmith API キー](https://docs.langchain.com/langsmith/create-account-api-key) を取得します。使用するプロジェクト名を決めておきます。 -LangSmith は LLM アプリケーションの開発、コラボレーション、テスト、デプロイ、監視などのツールを提供するプラットフォームです。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**LangSmith** の **設定** をクリックし、接続情報を入力してください。 - -LangSmith の公式サイト：[https://www.langchain.com/langsmith](https://www.langchain.com/langsmith) - +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **API Key** | はい | プロジェクトの読み取りとトレースの書き込み権限を持つキー。 | +| **プロジェクト** | はい | プロジェクト名。存在しない場合、最初のトレースの受信時に LangSmith が作成します。 | +| **Endpoint** | いいえ | 既定値は `https://api.smith.langchain.com`。独自の API エンドポイントには HTTPS が必須です。必要なパスプレフィックスも含めてください。 | -### 2 LangSmith の使い方 +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。LangSmith を選ぶと、現在の選択が置き換わります。 -#### 1. LangSmith の[公式サイト](https://www.langchain.com/langsmith)から登録し、ログインする。 +保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 -#### 2. LangSmith からプロジェクトを作成します +## Dify が送信するデータ -ログイン後、ホームページの **New Project** をクリックし、新たな **プロジェクト**を作成します。このプロジェクトは、Dify 内の **アプリ**と連動したデータモニタリングに使用されます。 +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 - - ![新たなプロジェクトを作成します。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) - +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 -作成する後、プロジェクトの中にチェクできます。 +LangSmith でモデルの実行を開くと、収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 - - ![LangSmith の中にプロジェクトをチェクします。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) - +### Agent の呼び出しと内容の収集 -#### 3. プロジェクト認証情報の作成 + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + -左のサイドバーでプロジェクト **設定** を見つける。 +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 - - ![プロジェクトを設定し](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) - +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -**Create API Key** をクリックし，新たな認証情報を作ります。 + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + - - ![プロジェクトの API Key を作ります。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) - +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 -**Personal Access Token** を選び，のちほとの API 身分証明の時使えます。 +## 新しいトレースの確認 - - ![Personal Access Token を選択します](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) - +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**LangSmith** の **見る** をクリックします。 +3. 設定したプロジェクトで、実行時刻を手がかりに新しい実行を探し、子の実行を確認します。 -新たな API key をコピーし、保存します。 +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 - - ![新たな API key をコピーします](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) - +最初のトレースを受信した後も **見る** でプロジェクト一覧が開く場合は、設定を再度保存してプロジェクトのリンクを更新してください。 -#### 4. Dify アプリの中に LangSmith を設定します +## トラブルシューティング -監視用のアプリのサイトメニューの **監視** ボタンをクリックし，**設定** をクリックします。 + + + 保存時にはプロジェクトへのアクセスを確認します。新しいプロジェクトは、最初のトレースの受信時に作成されます。LangSmith が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、設定した名前と一致するプロジェクトを確認します。 - - ![LangSmith を設定します](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/b6c7e5d4c2ca2092d59465cca27bc69c.png) - + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 -それから，LangSmith から作った **API Key** と **プロジェクト名**を **設定**の中に貼り付け、保存します。 - - - ![ LangSmith を設定します。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/93dfabcadb7b2ff597f54beb5e642124.png) - - - -設定したプロジェクト名は LangSmith のいるプロジェクト名と必ず一致します。一致しない場合、データの同期時に LangSmith は自動的に新しいプロジェクトを作成します。 - - -保存に成功すると、現在のページで監視状態を見ることができます。 - - - ![監視状態を見る](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/43369dc4de8f606c166fae2efab97d73.png) - - -### LangSmith でのモニタリングデータの表示 - -Dify 内のアプリケーションからデバッグや製品データを設定することで、LangSmith にてそのデータをモニタリングすることができます。 - - - ![Dify におけるアプリケーションのデバッグ](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/a1370fdbb79257cba31a565ac6764802.png) - - -LangSmith に切り替えると、ダッシュボード上で Dify アプリケーションの詳細な操作ログを見ることができます。 - - - ![LangSmith でのアプリケーションデータの表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) - - -LangSmith を通じて得られる詳細な大規模言語モデル（LLM）の操作ログは、Dify アプリケーションのパフォーマンスを最適化するために役立ちます。 - - - ![LangSmith でのアプリケーションデータの表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/beeb4ee50c80de8db7400c1f65727c8c.png) - - -### モニタリングデータリスト - -#### Workflow/Chatflow のトレース情報 - -Workflow や Chatflow を追跡するために使用されます。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ワークフローLangSmith Chain
workflow\_app\_log\_id/workflow\_run\_idID
user\_session\_id- メタデータに配置
{"workflow_{id}"}名前
start\_time開始時間
end\_time終了時間
inputs入力
outputs出力
モデルトークン消費使用メタデータ
metadata追加情報
エラーエラー
\[workflow]タグ
"conversation\_id/none for workflow"メタデータ内の conversation\_id
conversion\_id親実行 ID
-**ワークフロートレース情報** - -- workflow\_id：ワークフローの固有識別子 -- conversation\_id：会話 ID -- workflow\_run\_id：現在の実行 ID -- tenant\_id：テナント ID -- elapsed\_time：現在の実行にかかった時間 -- status：実行ステータス -- version：ワークフローのバージョン -- total\_tokens：現在の実行で使用されるトークンの合計数 -- file\_list：処理されたファイルのリスト -- triggered\_from：現在の実行を引き起こしたソース -- workflow\_run\_inputs：現在の実行の入力データ -- workflow\_run\_outputs：現在の実行の出力データ -- error：現在の実行中に発生したエラー -- query：実行中に使用されたクエリ -- workflow\_app\_log\_id：Workflow アプリケーションログ ID -- message\_id：関連メッセージ ID -- start\_time：実行の開始時間 -- end\_time：実行の終了時間 -- workflow node executions：ワークフローノード実行に関する情報 -- メタデータ - - workflow\_id：ワークフローの固有識別子 - - conversation\_id：会話 ID - - workflow\_run\_id：現在の実行 ID - - tenant\_id：テナント ID - - elapsed\_time：現在の実行にかかった時間 - - status：実行ステータス - - version：ワークフローのバージョン - - total\_tokens：現在の実行で使用されるトークンの合計数 - - file\_list：処理されたファイルのリスト - - triggered\_from：現在の実行を引き起こしたソース - -#### メッセージトレース情報 - -大規模言語モデル（LLM）関連の会話を追跡するために使用されます。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
チャットLangSmith LLM
message\_idID
user\_session\_id- メタデータに配置
{'"message_{id}"'}名前
start\_time開始時間
end\_time終了時間
inputs入力
outputs出力
モデルトークン消費使用メタデータ
metadata追加情報
エラーエラー
\["message", conversation\_mode]タグ
conversation\_idメタデータ内の conversation\_id
conversion\_id親実行 ID
-**メッセージトレース情報** - -- message\_id：メッセージ ID -- message\_data：メッセージデータ -- user\_session\_id：ユーザーセッション ID -- conversation\_model：会話モード -- message\_tokens：メッセージ中のトークン数 -- answer\_tokens：回答のトークン数 -- total\_tokens：メッセージと回答の合計トークン数 -- error：エラー情報 -- inputs：入力データ -- outputs：出力データ -- file\_list：処理されたファイルのリスト -- start\_time：開始時間 -- end\_time：終了時間 -- message\_file\_data：メッセージに関連付けられたファイルデータ -- conversation\_mode：会話モード -- メタデータ - - conversation\_id：会話 ID - - ls\_provider：モデルプロバイダ - - ls\_model\_name：モデル ID - - status：メッセージステータス - - from\_end\_user\_id：送信ユーザーの ID - - from\_account\_id：送信アカウントの ID - - agent\_based：メッセージがエージェントベースかどうか - - workflow\_run\_id：ワークフロー実行 ID - - from\_source：メッセージのソース - -#### モデレーショントレース情報 - -会話のモデレーションを追跡するために使用されます。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
モデレーションLangSmith Tool
user\_id- メタデータに配置
“moderation"名前
start\_time開始時間
end\_time終了時間
inputs入力
outputs出力
metadata追加情報
\[moderation]タグ
message\_id親実行 ID
-**モデレーショントレース情報** - -- message\_id：メッセージ ID -- user\_id：ユーザーID -- workflow\_app\_log\_id：Workflow アプリケーションログ ID -- inputs：モデレーションの入力データ -- message\_data：メッセージデータ -- flagged：コンテンツに注意が必要かどうか -- action：実行された具体的なアクション -- preset\_response：プリセット応答 -- start\_time：モデレーション開始時間 -- end\_time：モデレーション終了時間 -- メタデータ - - message\_id：メッセージ ID - - action：実行された具体的なアクション - - preset\_response：プリセット応答 - -#### 提案された質問トレース情報 - -提案された質問を追跡するために使用されます。 + プライベートネットワークのエンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx index 844ddb40c..20ca78fc0 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,537 +1,72 @@ --- title: Opik の統合 +sidebarTitle: Opik +description: Dify アプリを Opik に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-opik) を参照してください。 +## アプリの接続 -## Opik の概要 +ホスト型 Opik の API キーを取得するか、独自の Opik インスタンスを使用します。アカウントの準備については、[Opik の Dify 連携ガイド](https://www.comet.com/docs/opik/integrations/dify) を参照してください。独自のサーバー上の特定のワークスペースを使う場合は、その名前を管理者に確認します。 -Opik は、大規模言語モデル（LLM）アプリケーションを評価、テスト、および監視するためのオープンソースプラットフォームです。LLM ベースのアプリケーション開発において、直感的な評価・テスト・監視機能を提供し、開発効率の向上を支援します。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。Opik の項目（**オピック**）で **設定** をクリックし、接続情報を入力してください。 - -詳細については、[Opik](https://www.comet.com/site/products/opik/) をご参照ください。 - +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **API Key** | ホスト型 Opik では必須 | アカウントの API キー。認証を使用しないサーバーに限り、空欄にできます。 | +| **プロジェクト** | いいえ | プロジェクト名。最初のトレースの受信時に Opik が作成します。空欄の場合、Dify は `Default Project` を使用します。 | +| **Workspace** | いいえ | 既存のワークスペース。空欄の場合、Dify はアカウントの既定のワークスペースを使用します。認証なしのオープンソース版サーバーでは `default` を使用します。 | +| **Url** | いいえ | 既定値は `https://www.comet.com/opik/api/`。独自の HTTP(S) URL は末尾を `/api/` にしてください。 | ---- - -## Opik の導入ガイド - -### 1. [Opik](https://www.comet.com/signup?from=llm) に登録/ログイン - -### 2. Opik API キーの取得 - -右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 - - - ![Opik API キー](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) - - -### 3. Opik と Dify を統合 - -Dify アプリケーションで Opik を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 - - - ![アプリケーションパフォーマンスを追跡](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) - - -設定後、Opik で作成した **API Key** と **プロジェクト名** を設定ページに貼り付けて保存します。 - - - ![Opik の設定](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) - - -保存に成功すると、現在のページで監視ステータスを確認できます。 - -## 監視データの確認 - -設定が完了すると、Dify アプリケーションを通常通りデバッグまたは使用できます。すべての使用履歴は Opik で監視可能です。 - - - ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) - - -Opik に切り替えると、ダッシュボードで Dify アプリケーションの詳細な操作ログを確認できます。 - - - ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) - +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Opik を選ぶと、現在の選択が置き換わります。 -Opik の詳細な LLM 操作ログにより、Dify アプリケーションのパフォーマンスを最適化できます。 +保存済みの認証情報は、編集時には表示されません。**Url** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 - - ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) - +## Dify が送信するデータ -## モニタリングデータリスト +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 -### **ワークフロー/会話フロートラッキング情報** +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 -**ワークフローと会話フローの追跡に使用** +Opik で LLM スパンを開くと、モデル呼び出しで収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ワークフローOpik トラッキング
workflow_app_log_id/workflow_run_idid
user_session_id- メタデータに配置
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**ワークフロートラッキング情報** +### Agent の呼び出しと内容の収集 -- workflow_id - ワークフローの一意識別子 -- conversation_id - 会話 ID -- workflow_run_id - 現在の実行 ID -- tenant_id - テナント ID -- elapsed_time - 現在の実行にかかった時間 -- status - 実行ステータス -- version - ワークフローバージョン -- total_tokens - 現在の実行で使用されたトークン総数 -- file_list - 処理されたファイルのリスト -- triggered_from - 実行をトリガーしたソース -- workflow_run_inputs - 現在の実行の入力データ -- workflow_run_outputs - 現在の実行の出力データ -- error - 実行中に発生したエラー -- query - 実行中に使用されたクエリ -- workflow_app_log_id - Workflow アプリケーションログ ID -- message_id - 関連するメッセージ ID -- start_time - 実行開始時間 -- end_time - 実行終了時間 -- workflow node executions - ワークフローノードの実行情報 -- メタデータ - - workflow_id - ワークフローの一意識別子 - - conversation_id - 会話 ID - - workflow_run_id - 現在の実行 ID - - tenant_id - テナント ID - - elapsed_time - 現在の実行にかかった時間 - - status - 実行ステータス - - version - ワークフローバージョン - - total_tokens - 現在の実行で使用されたトークン総数 - - file_list - 処理されたファイルのリスト - - triggered_from - 実行をトリガーしたソース + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + ---- - -### **メッセージトラッキング情報** - -**LLM 関連の会話を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
チャットOpik LLM
message_idid
user_session_id- メタデータに配置
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**メッセージトラッキング情報** - -- message_id - メッセージ ID -- message_data - メッセージデータ -- user_session_id - ユーザーセッション ID -- conversation_model - 会話モード -- message_tokens - メッセージ内のトークン数 -- answer_tokens - 回答内のトークン数 -- total_tokens - メッセージと回答のトークン総数 -- error - エラー情報 -- inputs - 入力データ -- outputs - 出力データ -- file_list - 処理されたファイルリスト -- start_time - 開始時間 -- end_time - 終了時間 -- message_file_data - メッセージ関連のファイルデータ -- conversation_mode - 会話モード -- メタデータ - - conversation_id - 会話 ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージソース +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 -### **レビュー追跡情報** +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -**会話のレビューを追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
レビューOpik Tool
user_id- メタデータに配置
"moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**レビュー追跡情報** - -- message_id - メッセージ ID -- user_id - ユーザーID -- workflow_app_log_id - Workflow アプリケーションログ ID -- inputs - レビュー入力データ -- message_data - メッセージデータ -- flagged - 注意が必要とマークされたかどうか -- action - 実施された具体的なアクション -- preset_response - プリセットレスポンス -- start_time - レビュー開始時間 -- end_time - レビュー終了時間 -- メタデータ - - message_id - メッセージ ID - - action - 実施されたアクション - - preset_response - プリセットレスポンス - ---- + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + -### **提案質問追跡情報** +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 -**提案質問を追跡するために使用** +## 新しいトレースの確認 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
提案質問Opik LLM
user_id- メタデータに配置
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**提案質問追跡情報** +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**オピック** の **見る** をクリックします。コンソールが開いた場合は、設定したワークスペースとプロジェクトを選択します。 +3. 実行時刻を手がかりに新しいトレースを探し、開いてスパンを確認します。 -- message_id - メッセージ ID -- message_data - メッセージデータ -- inputs - 入力データ -- outputs - 出力データ -- start_time - 開始時間 -- end_time - 終了時間 -- total_tokens - トークン総数 -- status - メッセージステータス -- error - エラー情報 -- from_account_id - 送信アカウント ID -- agent_based - エージェントベースかどうか -- from_source - メッセージの送信元 -- model_provider - モデルプロバイダー -- model_id - モデル ID -- suggested_question - 提案された質問 -- level - ステータスレベル -- status_message - ステータスメッセージ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- - -### **データセット検索追跡情報** - -**ナレッジベース検索を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
データセット検索Opik Retriever
user_id- メタデータに配置
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**データセット検索追跡情報** - -- message_id - メッセージ ID -- inputs - 入力データ -- documents - ドキュメントデータ -- start_time - 開始時間 -- end_time - 終了時間 -- message_data - メッセージデータ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 -### **ツール追跡情報** +## トラブルシューティング -**ツールの呼び出しを追跡するために使用** + + + 保存時にはワークスペースへのアクセスを確認します。プロジェクトは、最初のトレースの受信時に Opik が作成します。Opik が選択され、トレースが有効になっていることを確認してください。Opik で、Dify に設定したワークスペースとプロジェクトを開き、アプリを再度実行します。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ツールOpik Tool
user_id- メタデータに配置
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-**ツール追跡情報** + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 -- message_id - メッセージ ID -- tool_name - ツール名 -- start_time - 開始時間 -- end_time - 終了時間 -- tool_inputs - ツール入力 -- tool_outputs - ツール出力 -- message_data - メッセージデータ -- error - エラー情報（該当する場合） -- inputs - メッセージの入力 -- outputs - メッセージの出力 -- tool_config - ツール設定 -- time_cost - 時間コスト -- tool_parameters - ツールパラメーター -- file_url - 関連するファイルの URL -- メタデータ - - message_id - メッセージ ID - - tool_name - ツール名 - - tool_inputs - ツール入力 - - tool_outputs - ツール出力 - - tool_config - ツール設定 - - time_cost - 時間コスト - - error - エラー情報（該当する場合） - - tool_parameters - ツールパラメーター - - message_file_id - メッセージファイル ID - - created_by_role - 作成者の役割 - - created_user_id - 作成者ユーザーID + プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index e00cd799f..9f8e0b460 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,567 +1,75 @@ --- title: Phoenix の統合 +sidebarTitle: Phoenix +description: Dify アプリを Phoenix に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-phoenix) を参照してください。 +## アプリの接続 -### 1 Phoenix とは +Dify の各サービスから接続できる Phoenix インスタンスを使用します。セルフホストでも Phoenix Cloud でも利用できます。認証が必要な場合は、プロジェクトの読み取りとトレースの送信ができる [API キー](https://arize.com/docs/phoenix/settings/api-keys) を取得します。Arize に接続する場合は、[Arize 連携](/ja/self-host/use-dify/monitor/integrations/integrate-arize) の手順に従ってください。 -[Arize Phoenix](https://arize.com/phoenix/) は、[Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) が提供するオープンソースのプラットフォームです。OpenTelemetry をベースに、LLM ワークフローとエージェントの可観測性、評価、プロンプトエンジニアリング、実験に対応します。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Phoenix** の **設定** をクリックし、接続情報を入力してください。 -開発中は Phoenix をローカルで実行できます。自社インフラに単一コンテナとしてセルフホストするか、Arize がホストする [Phoenix Cloud](#3-phoenix-cloud-の使い方) を利用することもできます。 +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **API Key** | 認証が有効な場合 | インスタンスまたは Phoenix Cloud スペースのキー。認証なしのサーバーでは空欄にします。 | +| **プロジェクト** | はい | 送信先のプロジェクト名。 | +| **Endpoint** | いいえ | Phoenix のベース URL。既定値の `https://app.phoenix.arize.com` を、Cloud スペースまたはセルフホストのインスタンスの URL に置き換えます。パスプレフィックスも含めてください。 | -本番運用チームや AI ネイティブ企業、エンタープライズにはフル機能の [Arize AX](https://arize.com/products/ax/) が適しています。必要な場合は、代わりに [Arize 統合](/ja/self-host/use-dify/monitor/integrations/integrate-arize) を設定してください。 +Phoenix Cloud では、`https://app.phoenix.arize.com/s/` など、スペースのホスト名をコピーします。取得場所は [Phoenix エンドポイントの確認方法](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint) を参照してください。ベース URL に `/v1/traces` は含めません。このパスは Dify が追加します。 -トレースの送信が始まったら、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。障害のデバッグ、エージェント動作の評価、モデル品質のモニタリングにトレースを活用する方法を確認できます。 +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Phoenix を選ぶと、現在の選択が置き換わります。 -### 2 Phoenix の使い方 +保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 -#### 1. Phoenix の[公式サイト](https://app.arize.com/auth/phoenix/signup)から登録し、ログインする。 +## Dify が送信するデータ -### 2. Phoenix API キーの取得 +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 -右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 - - ![Phoenix API キー](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) - +Phoenix でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify は Phoenix に標準で用意されている費用フィールドには値を設定しません。 -### 3. Phoenix と Dify を統合 +### Agent の呼び出しと内容の収集 -Dify アプリケーションで Phoenix を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + - - ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 -設定後、Phoenix で作成した **API Key** と **プロジェクト名** を設定ページに貼り付けて保存します。 +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 - - ![Phoenix の設定](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + -保存に成功すると、現在のページで監視ステータスを確認できます。 +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 - - ![Phoenix の設定](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - +## 新しいトレースの確認 -### 3 Phoenix Cloud の使い方 +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**Phoenix** の **見る** をクリックして設定したプロジェクトを開きます。 +3. 実行時刻を手がかりに新しいトレースを探し、開いて子のスパンを確認します。 -#### 1. Phoenix Cloud の[公式サイト](https://app.arize.com/auth/phoenix/signup)から登録し、ログインする。 +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 -### 2. Phoenix スペースの作成 +## トラブルシューティング -右上のユーザーメニューから Phoenix スペースを作成できます。スペースを作成 をクリックし、スペース用の一意の URL 識別子を入力してください。 + + + 保存時にはプロジェクトの読み取り権限を確認します。トレースは送信しません。Phoenix が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、設定したプロジェクトを確認します。 - - ![Phoenix Cloud で Space を作成](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) - + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 -保存に成功すると、概要ページでスペースのステータスを確認できます。 + プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + - - ![Phoenix Cloud Space の概要](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) - - -### 3. Phoenix API キーの作成 - -スペースを起動した後、左下のユーザーメニューから 設定 を開き、Phoenix API キーを作成できます。システムキー をクリックし、API キーの名前を入力してください。 - - - ![Phoenix Cloud API キー](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) - - -### 4. Phoenix Cloud と Dify を統合 - -Dify アプリケーションで Phoenix を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 - - - ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - - -設定画面で、Phoenix Cloud で作成した API キー、プロジェクト名、および スペースのホスト名 を入力して保存してください。 - - - ![Phoenix の設定](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - - -保存に成功すると、現在のページで監視ステータスを確認できます。 - - - ![Phoenix の設定](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - - -## モニタリングデータリスト - -### **ワークフロー/会話フロートラッキング情報** - -**ワークフローと会話フローの追跡に使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ワークフローPhoenix トラッキング
workflow_app_log_id/workflow_run_idid
user_session_id- メタデータに配置
{"workflow_{id}"}name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
errorerror
\[workflow]tags
"conversation_id/none for workflow"conversation_id in metadata
-**ワークフロートラッキング情報** - -- workflow_id - ワークフローの一意識別子 -- conversation_id - 会話 ID -- workflow_run_id - 現在の実行 ID -- tenant_id - テナント ID -- elapsed_time - 現在の実行にかかった時間 -- status - 実行ステータス -- version - ワークフローバージョン -- total_tokens - 現在の実行で使用されたトークン総数 -- file_list - 処理されたファイルのリスト -- triggered_from - 実行をトリガーしたソース -- workflow_run_inputs - 現在の実行の入力データ -- workflow_run_outputs - 現在の実行の出力データ -- error - 実行中に発生したエラー -- query - 実行中に使用されたクエリ -- workflow_app_log_id - Workflow アプリケーションログ ID -- message_id - 関連するメッセージ ID -- start_time - 実行開始時間 -- end_time - 実行終了時間 -- workflow node executions - ワークフローノードの実行情報 -- メタデータ - - workflow_id - ワークフローの一意識別子 - - conversation_id - 会話 ID - - workflow_run_id - 現在の実行 ID - - tenant_id - テナント ID - - elapsed_time - 現在の実行にかかった時間 - - status - 実行ステータス - - version - ワークフローバージョン - - total_tokens - 現在の実行で使用されたトークン総数 - - file_list - 処理されたファイルのリスト - - triggered_from - 実行をトリガーしたソース - ---- - -### **メッセージトラッキング情報** - -**LLM 関連の会話を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
チャットPhoenix LLM
message_idid
user_session_id- メタデータに配置
"llm"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
モデルトークン消費usage_metadata
metadatametadata
\["message", conversation_mode]tags
conversation_idconversation_id in metadata
-**メッセージトラッキング情報** - -- message_id - メッセージ ID -- message_data - メッセージデータ -- user_session_id - ユーザーセッション ID -- conversation_model - 会話モード -- message_tokens - メッセージ内のトークン数 -- answer_tokens - 回答内のトークン数 -- total_tokens - メッセージと回答のトークン総数 -- error - エラー情報 -- inputs - 入力データ -- outputs - 出力データ -- file_list - 処理されたファイルリスト -- start_time - 開始時間 -- end_time - 終了時間 -- message_file_data - メッセージ関連のファイルデータ -- conversation_mode - 会話モード -- メタデータ - - conversation_id - 会話 ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージソース - -### **レビュー追跡情報** - -**会話のレビューを追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
レビューPhoenix Tool
user_id- メタデータに配置
"moderation"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["moderation"]tags
-**レビュー追跡情報** - -- message_id - メッセージ ID -- user_id - ユーザーID -- workflow_app_log_id - Workflow アプリケーションログ ID -- inputs - レビュー入力データ -- message_data - メッセージデータ -- flagged - 注意が必要とマークされたかどうか -- action - 実施された具体的なアクション -- preset_response - プリセットレスポンス -- start_time - レビュー開始時間 -- end_time - レビュー終了時間 -- メタデータ - - message_id - メッセージ ID - - action - 実施されたアクション - - preset_response - プリセットレスポンス - ---- - -### **提案質問追跡情報** - -**提案質問を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
提案質問Phoenix LLM
user_id- メタデータに配置
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["suggested_question"]tags
-**提案質問追跡情報** - -- message_id - メッセージ ID -- message_data - メッセージデータ -- inputs - 入力データ -- outputs - 出力データ -- start_time - 開始時間 -- end_time - 終了時間 -- total_tokens - トークン総数 -- status - メッセージステータス -- error - エラー情報 -- from_account_id - 送信アカウント ID -- agent_based - エージェントベースかどうか -- from_source - メッセージの送信元 -- model_provider - モデルプロバイダー -- model_id - モデル ID -- suggested_question - 提案された質問 -- level - ステータスレベル -- status_message - ステータスメッセージ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- - -### **データセット検索追跡情報** - -**ナレッジベース検索を追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
データセット検索Phoenix Retriever
user_id- メタデータに配置
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["dataset_retrieval"]tags
message_idparent_run_id
-**データセット検索追跡情報** - -- message_id - メッセージ ID -- inputs - 入力データ -- documents - ドキュメントデータ -- start_time - 開始時間 -- end_time - 終了時間 -- message_data - メッセージデータ -- メタデータ - - message_id - メッセージ ID - - ls_provider - モデルプロバイダー - - ls_model_name - モデル ID - - status - メッセージステータス - - from_end_user_id - 送信ユーザーID - - from_account_id - 送信アカウント ID - - agent_based - エージェントベースかどうか - - workflow_run_id - ワークフロー実行 ID - - from_source - メッセージの送信元 - ---- - -### **ツール追跡情報** - -**ツールの呼び出しを追跡するために使用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ツールPhoenix Tool
user_id- メタデータに配置
tool_namename
start_timestart_time
end_timeend_time
inputsinputs
outputsoutputs
metadatametadata
\["tool", tool_name]tags
-**ツール追跡情報** - -- message_id - メッセージ ID -- tool_name - ツール名 -- start_time - 開始時間 -- end_time - 終了時間 -- tool_inputs - ツール入力 -- tool_outputs - ツール出力 -- message_data - メッセージデータ -- error - エラー情報（該当する場合） -- inputs - メッセージの入力 -- outputs - メッセージの出力 -- tool_config - ツール設定 -- time_cost - 時間コスト -- tool_parameters - ツールパラメーター -- file_url - 関連するファイルの URL -- メタデータ - - message_id - メッセージ ID - - tool_name - ツール名 - - tool_inputs - ツール入力 - - tool_outputs - ツール出力 - - tool_config - ツール設定 - - time_cost - 時間コスト - - error - エラー情報（該当する場合） - - tool_parameters - ツールパラメーター - - message_file_id - メッセージファイル ID - - created_by_role - 作成者の役割 - - created_user_id - 作成者ユーザーID +収集したトレースの評価方法については、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。 diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx index 8169f51b2..2de4403e3 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -6,346 +6,70 @@ description: Dify アプリケーションからトレースを W&B Weave に送 > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-weave) を参照してください。 - - Dify v1.3.1 以上が必要です。 - +## アプリの接続 -### W&B Weave とは +Dify を設定する前に、[API キー](https://wandb.ai/authorize) で書き込める [W&B プロジェクト](https://docs.wandb.ai/models/track/project-page#create-a-project) を作成します。チームのプロジェクトでは、そのチームを **Entity** に指定します。 -Weights & Biases (W&B) Weave は、LLM ベースのアプリケーションの追跡、実験、評価、デプロイ、改善のためのフレームワークです。柔軟性とスケーラビリティを考慮して設計された Weave は、LLM アプリケーション開発ワークフローのあらゆる段階をサポートします。 +Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。Weave の項目（**織る**）で **設定** をクリックし、接続情報を入力してください。 - - 詳細については、[Weave](https://docs.wandb.ai/weave) を参照してください。 - +| フィールド | 必須 | 値 | +|:------|:---------|:------| +| **API Key** | はい | W&B の API キー。 | +| **プロジェクト** | はい | 書き込み可能な既存のプロジェクト。ここに `entity/project` を入力して、**Entity** を空欄にしてもかまいません。 | +| **Entity** | いいえ | W&B のチームまたはユーザー。空欄の場合、Dify は API キーの既定のエンティティを取得します。 | +| **Endpoint** | いいえ | Weave のトレースサーバー。既定値は `https://trace.wandb.ai`。HTTPS が必須です。 | +| **Host** | いいえ | W&B の API サーバー。既定値は `https://api.wandb.ai`。HTTP(S) を使用できます。 | -### Weave の設定方法 +独自のデプロイ先を使う場合は、トレースサーバーの **Endpoint** と W&B API の **Host** を管理者に確認します。指定されたパスプレフィックスも含めてください。 -#### 1. [W&B Weave](https://wandb.ai/signup)に登録/ログイン +[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Weave を選ぶと、現在の選択が置き換わります。 -API キーを取得する +保存済みの認証情報は、編集時には表示されません。**Host** と **Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。どちらかのアドレスを変更した場合は、認証情報を再入力してください。 -次に、https://wandb.ai で Weights & Biases (W&B) アカウントを作成し、https://wandb.ai/authorize から API キーをコピーします +## Dify が送信するデータ -#### 2. W&B Weave を Dify と統合する +トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 -Dify アプリケーションで Weave を設定します。監視が必要なアプリケーションを開き、サイドメニューの **モニタリング** を開き、ページ上の **アプリケーションパフォーマンスの追跡** を選択します。 +Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 - - ![Dify アプリケーションで Weave を設定します](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) - +Weave でモデル呼び出しを開くと、収集した入出力を確認できます。取得できた token 数は、呼び出しのモデル別使用量に表示されます。Dify は Weave に標準で用意されている費用フィールドには値を設定しません。 -設定をクリックした後、**API キー** と**プロジェクト名** を貼り付け、**W&B エンティティ**（オプション、デフォルトはユーザー名）も指定して設定を保存します。 +### Agent の呼び出しと内容の収集 - - ![](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) - + +Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 + -正常に保存されると、現在のページで監視状態を確認できます。 +アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 - - ![](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) - +- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 +- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 -### Weave でモニタリングデータを表示する + +これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 + -設定が完了すると、Dify 内のアプリケーションからのデバッグまたは本番データを Weave で監視できます。 +新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 - - ![](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) - +## 新しいトレースの確認 -Weave に切り替えると、ダッシュボードで Dify アプリケーションの詳細な操作ログを確認できます。 +1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 +2. **アプリのパフォーマンスの追跡** で、**織る** の **見る** をクリックして設定したプロジェクトを開きます。 +3. 実行時刻を手がかりに新しい呼び出しを探し、開いて子の呼び出しを確認します。 - - ![](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) - +実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 -Weave を通じた詳細な LLM 操作ログは、Dify アプリケーションのパフォーマンスを最適化するのに役立ちます。 +## トラブルシューティング -### モニタリングデータリスト + + + 保存時には、プロジェクトが存在し、書き込み可能であることと、トレースサーバーに接続できることを確認します。Weave が選択され、トレースが有効になっていることを確認してください。Weave で、Dify に設定したエンティティとプロジェクトを開き、アプリを再度実行します。 -#### **Workflow/Chatflow トレース情報** + 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 + + + Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 -**Workflow と Chatflow を追跡するために使用** - -| ワークフロー | Weave トレース | -| ------------------------------------ | ---------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | メタデータに配置 | -| workflow_\{id\} | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| モデルトークン消費量 | usage_metadata | -| metadata | extra | -| error | error | -| workflow | tags | -| "conversation_id/none for workflow" | メタデータ内の conversation_id | -| conversion_id | parent_run_id | - -**ワークフロートレース情報** - -* workflow_id - ワークフローの一意の識別子 -* conversation_id - 会話 ID -* workflow_run_id - 現在の実行の ID -* tenant_id - テナント ID -* elapsed_time - 現在の実行にかかった時間 -* status - 実行ステータス -* version - ワークフローバージョン -* total_tokens - 現在の実行で使用されたトークンの総数 -* file_list - 処理されたファイルのリスト -* triggered_from - 現在の実行をトリガーしたソース -* workflow_run_inputs - 現在の実行の入力データ -* workflow_run_outputs - 現在の実行の出力データ -* error - 現在の実行中に発生したエラー -* query - 実行中に使用されたクエリ -* workflow_app_log_id - Workflow アプリケーションログ ID -* message_id - 関連するメッセージ ID -* start_time - 実行の開始時間 -* end_time - 実行の終了時間 -* workflow node executions - ワークフローノード実行に関する情報 -* メタデータ - * workflow_id - ワークフローの一意の識別子 - * conversation_id - 会話 ID - * workflow_run_id - 現在の実行の ID - * tenant_id - テナント ID - * elapsed_time - 現在の実行にかかった時間 - * status - 実行ステータス - * version - ワークフローバージョン - * total_tokens - 現在の実行で使用されたトークンの総数 - * file_list - 処理されたファイルのリスト - * triggered_from - 現在の実行をトリガーしたソース - -#### **メッセージトレース情報** - -**LLM 関連の会話を追跡するために使用** - -| チャット | Weave トレース | -| ---------------------------------- | ----------------------------- | -| message_id | id | -| user_session_id | メタデータに配置 | -| "message_\{id\}" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| モデルトークン消費量 | usage_metadata | -| metadata | extra | -| error | error | -| "message", conversation_mode | tags | -| conversation_id | メタデータ内の conversation_id | -| conversion_id | parent_run_id | - -**メッセージトレース情報** - -* message_id - メッセージ ID -* message_data - メッセージデータ -* user_session_id - ユーザーセッション ID -* conversation_model - 会話モード -* message_tokens - メッセージ内のトークン数 -* answer_tokens - 回答内のトークン数 -* total_tokens - メッセージと回答内のトークンの総数 -* error - エラー情報 -* inputs - 入力データ -* outputs - 出力データ -* file_list - 処理されたファイルのリスト -* start_time - 開始時間 -* end_time - 終了時間 -* message_file_data - メッセージに関連するファイルデータ -* conversation_mode - 会話モード -* メタデータ - * conversation_id - 会話 ID - * ls_provider - モデルプロバイダー - * ls_model_name - モデル ID - * status - メッセージステータス - * from_end_user_id - 送信ユーザーの ID - * from_account_id - 送信アカウントの ID - * agent_based - メッセージがエージェントベースかどうか - * workflow_run_id - ワークフロー実行 ID - * from_source - メッセージソース - -#### **モデレーショントレース情報** - -**会話モデレーションを追跡するために使用** - -| モデレーション | Weave トレース | -| ------------- | ----------------------- | -| user_id | メタデータに配置 | -| "moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[moderation] | tags | -| message_id | parent_run_id | - -**モデレーショントレース情報** - -* message_id - メッセージ ID -* user_id: ユーザーID -* workflow_app_log_id - Workflow アプリケーションログ ID -* inputs - モデレーション入力データ -* message_data - メッセージデータ -* flagged - コンテンツが注意対象としてフラグ付けされているかどうか -* action - 取られた特定のアクション -* preset_response - プリセット応答 -* start_time - モデレーション開始時間 -* end_time - モデレーション終了時間 -* メタデータ - * message_id - メッセージ ID - * action - 取られた特定のアクション - * preset_response - プリセット応答 - -#### **提案質問トレース情報** - -**提案された質問を追跡するために使用** - -| 提案質問 | Weave トレース | -| ---------------------- | ----------------------- | -| user_id | メタデータに配置 | -| suggested_question | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| suggested_question | tags | -| message_id | parent_run_id | - -**メッセージトレース情報** - -* message_id - メッセージ ID -* message_data - メッセージデータ -* inputs - 入力内容 -* outputs - 出力内容 -* start_time - 開始時間 -* end_time - 終了時間 -* total_tokens - トークン数 -* status - メッセージステータス -* error - エラー情報 -* from_account_id - 送信アカウントの ID -* agent_based - メッセージがエージェントベースかどうか -* from_source - メッセージソース -* model_provider - モデルプロバイダー -* model_id - モデル ID -* suggested_question - 提案された質問 -* level - ステータスレベル -* status_message - ステータスメッセージ -* メタデータ - * message_id - メッセージ ID - * ls_provider - モデルプロバイダー - * ls_model_name - モデル ID - * status - メッセージステータス - * from_end_user_id - 送信ユーザーの ID - * from_account_id - 送信アカウントの ID - * workflow_run_id - ワークフロー実行 ID - * from_source - メッセージソース - -#### **データセット検索トレース情報** - -**ナレッジベース検索を追跡するために使用** - -| データセット検索 | Weave トレース | -| --------------------- | ----------------------- | -| user_id | メタデータに配置 | -| dataset_retrieval | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| dataset_retrieval | tags | -| message_id | parent_run_id | - -**データセット検索トレース情報** - -* message_id - メッセージ ID -* inputs - 入力内容 -* documents - ドキュメントデータ -* start_time - 開始時間 -* end_time - 終了時間 -* message_data - メッセージデータ -* メタデータ - * message_id - メッセージ ID - * ls_provider - モデルプロバイダー - * ls_model_name - モデル ID - * status - メッセージステータス - * from_end_user_id - 送信ユーザーの ID - * from_account_id - 送信アカウントの ID - * agent_based - メッセージがエージェントベースかどうか - * workflow_run_id - ワークフロー実行 ID - * from_source - メッセージソース - -#### **ツールトレース情報** - -**ツール呼び出しを追跡するために使用** - -| ツール | Weave トレース | -| --------------------- | ----------------------- | -| user_id | メタデータに配置 | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \["tool", tool_name] | tags | -| message_id | parent_run_id | - -#### **ツールトレース情報** - -* message_id - メッセージ ID -* tool_name - ツール名 -* start_time - 開始時間 -* end_time - 終了時間 -* tool_inputs - ツール入力 -* tool_outputs - ツール出力 -* message_data - メッセージデータ -* error - エラー情報（もしあれば） -* inputs - メッセージの入力 -* outputs - メッセージの出力 -* tool_config - ツール設定 -* time_cost - 時間コスト -* tool_parameters - ツールパラメータ -* file_url - 関連ファイルの URL -* メタデータ - * message_id - メッセージ ID - * tool_name - ツール名 - * tool_inputs - ツール入力 - * tool_outputs - ツール出力 - * tool_config - ツール設定 - * time_cost - 時間コスト - * error - エラー情報（もしあれば） - * tool_parameters - ツールパラメータ - * message_file_id - メッセージファイル ID - * created_by_role - 作成者のロール - * created_user_id - 作成者のユーザーID - -**名前生成トレース情報** - -**会話タイトル生成を追跡するために使用** - -| 名前生成 | Weave トレース | -| ----------------- | ----------------------- | -| user_id | メタデータに配置 | -| generate_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| generate_name | tags | - -**名前生成トレース情報** - -* conversation_id - 会話 ID -* inputs - 入力データ -* outputs - 生成された会話名 -* start_time - 開始時間 -* end_time - 終了時間 -* tenant_id - テナント ID -* メタデータ - * conversation_id - 会話 ID - * tenant_id - テナント ID + プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 + + diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index 9637d6078..aa2e7c1bf 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -1,197 +1,82 @@ --- title: 集成阿里云云监控 +sidebarTitle: 阿里云云监控 +description: 通过 OpenTelemetry 将 Dify 应用的追踪数据发送至阿里云云监控（ARMS） --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-aliyun)。 -## 什么是阿里云云监控 +## 连接应用 -阿里云提供的全托管免运维可观测平台，一键开启 Dify 应用的监控追踪和评估。 +让部署管理员参考 [阿里云接入说明](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin)，提供 License Key 和 HTTP 追踪 URL。管理员应选择 Dify 服务可访问的地域和网络地址。 - -阿里云云监控原生支持 Python/Golang/Java 应用通过 [LoongSuite](https://github.com/alibaba/loongsuite-python-agent) -探针 & 开源 OpenTelemetry 探针接入，在一键开启 Dify 大模型应用监控外，还支持通过无侵入探针对 Dify 组件及其上下游依赖的全链路可观测。 -更多详情，请参考 [阿里云官方文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/user-guide/model-application)。 - +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **云监控** 的 **配置**，填写连接信息： -## 如何配置云监控 +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **License Key** | 是 | 采集器的认证密钥，与端点分开填写。 | +| **Endpoint** | 是 | 采集器的 HTTP(S) 基础 URL，可包含端口号。 | +| **App Name** | 是 | 自定义应用名称，用于在 ARMS 控制台中显示。 | -### 1. 获取阿里云 Endpoint 和 License Key +将 HTTP 追踪 URL 中 `/adapt_` 之前的部分填入 **Endpoint**，将认证令牌 填入 **License Key**。例如，HTTP 追踪 URL 为： -1. 登录 [ARMS 控制台](https://arms.console.aliyun.com/)，在左侧导航栏单击 **接入中心**。 -2. 在 **服务端应用** 区域单击 **OpenTelemetry** 卡片。 -3. 在弹出的 **OpenTelemetry** 面板中选择数据上报方式为 **gRPC**，并依据实际部署情况选择连接方式和地域。 +```text +https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces +``` - - ![P976945](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/3938280571/p976945.png) - +- **Endpoint**：`https://tracing-analysis-dc-hz.aliyuncs.com` +- **License Key**：`example-key` -4. 保存 **公网接入点（Endpoint）** 和 **鉴权 Token（License Key）**。 -> **说明** -> Endpoint 不带端口号，例如 `http://tracing-cn-heyuan.arms.aliyuncs.com`。 +保留 HTTP 端点中的端口号；此处不能使用 `8090` 等 gRPC 端口。 -### 2. 将云监控与 Dify 集成 - - - 需要 Dify v1.6.0 或更高版本。 - - -1. 登录 **Dify 控制台**，并进入需要监控的 Dify 应用。 -2. 在左侧导航栏单击 **监测**。 -3. 单击 **追踪应用性能**，然后在 **云监控** 区域单击 **配置**。 - - - ![P984812](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9647222571/p984812.png) - - -4. 在弹出的对话框中输入步骤 1 获取的 **License Key** 和 **Endpoint**，并自定义 **App Name**（ARMS 控制台显示的应用名称），然后单击 **保存并启用**。 - -## 在云监控中查看监控数据 - -配置完成后，Dify 内应用的调试或生产数据可以在 **云监控** 中进行监控。 - -### 方式一：从 Dify 应用跳转 ARMS 控制台 - -在 Dify 控制台选择已开启应用追踪的应用，进入 **追踪配置**，在 **云监控** 区域单击 **查看**。 - - - ![P984818](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9647222571/p984818.png) - - -### 方式二：直接在 ARMS 控制台查看 - -在 ARMS 控制台的 **LLM 应用监控 > 应用列表** 页面进入对应的 Dify 应用。 - -## 接入更多数据 - -云监控提供了多语言无侵入探针，支持接入 Dify 集群的各个组件，实现全链路追踪。 - -| Dify 组件 | 探针 | 详情 | -|---------------|--------------------|----------------| -| Nginx | OpenTelemetry 探针 | [使用 OpenTelemetry 对 Nginx 进行链路追踪](https://help.aliyun.com/zh/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx) | -| Api | LoongSuite-Python 探针 | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | -| Sandbox | LoongSuite-Go 探针 | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -| Worker | OpenTelemetry 探针 | [通过 OpenTelemetry 上报 Python 应用数据](https://help.aliyun.com/zh/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications) | -| Plugin-Daemon | LoongSuite-Go 探针 | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | - -## 监测数据清单 - -云监控支持采集 Dify 的 Workflow/Chatflow/Chat/Agent 应用，采集数据包括工作流和工作流节点的执行明细，涵盖模型调用、工具调用、知识检索和各类流程节点的执行明细数据以及会话和用户信息等元数据 - -### Workflow/Chatflow Trace 信息 - -**Workflow Trace Info** - -* workflow\_id - Workflow 的唯一标识 -* conversation\_id - 对话 ID -* workflow\_run\_id - 此次运行的 ID -* tenant\_id - 租户 ID -* elapsed\_time - 此次运行耗时 -* status - 运行状态 -* version - Workflow 版本 -* total\_tokens - 此次运行使用的 token 总数 -* file\_list - 处理的文件列表 -* triggered\_from - 触发此次运行的来源 -* workflow\_run\_inputs - 此次运行的输入数据 -* workflow\_run\_outputs - 此次运行的输出数据 -* error - 此次运行中发生的错误 -* query - 运行时使用的查询 -* workflow\_app\_log\_id - Workflow 应用日志 ID -* message\_id - 关联的消息 ID -* start\_time - 运行开始时间 -* end\_time - 运行结束时间 -* workflow node executions - workflow 节点运行信息 -* Metadata - * workflow\_id - Workflow 的唯一标识 - * conversation\_id - 对话 ID - * workflow\_run\_id - 此次运行的 ID - * tenant\_id - 租户 ID - * elapsed\_time - 此次运行耗时 - * status - 运行状态 - * version - Workflow 版本 - * total\_tokens - 此次运行使用的 token 总数 - * file\_list - 处理的文件列表 - * triggered\_from - 触发来源 - -### Message Trace 信息 - -**Message Trace Info** - -* message\_id - 消息 ID -* message\_data - 消息数据 -* user\_session\_id - 用户的 session\_id -* conversation\_model - 对话模式 -* message\_tokens - 消息中的令牌数 -* answer\_tokens - 回答中的令牌数 -* total\_tokens - 消息和回答中的总令牌数 -* error - 错误信息 -* inputs - 输入数据 -* outputs - 输出数据 -* file\_list - 处理的文件列表 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_file\_data - 消息关联的文件数据 -* conversation\_mode - 对话模式 -* Metadata - * conversation\_id - 消息所属对话的 ID - * ls\_provider - 模型提供者 - * ls\_model\_name - 模型 ID - * status - 消息状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户的 ID - * agent\_based - 是否基于代理 - * workflow\_run\_id - 工作流运行 ID - * from\_source - 消息来源 - * message\_id - 消息 ID - -### Dataset Retrieval Trace 信息 - -**Dataset Retrieval Trace Info** - -* message\_id - 消息 ID -* inputs - 输入内容 -* documents - 文档数据 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_data - 消息数据 -* Metadata - * message\_id 消息 ID - * ls\_provider 模型提供者 - * ls\_model\_name 模型 ID - * status 消息状态 - * from\_end\_user\_id 发送用户的 ID - * from\_account\_id 发送账户的 ID - * agent\_based 是否基于代理 - * workflow\_run\_id 工作流运行 ID - * from\_source 消息来源 - -### Tool Trace 信息 - -**Tool Trace Info** - -* message\_id 消息 ID -* tool\_name 工具名称 -* start\_time 开始时间 -* end\_time 结束时间 -* tool\_inputs 工具输入 -* tool\_outputs 工具输出 -* message\_data 消息数据 -* error 错误信息，如果存在 -* inputs 消息的输入内容 -* outputs 消息的回答内容 -* tool\_config 工具配置 -* time\_cost 时间成本 -* tool\_parameters 工具参数 -* file\_url 关联文件的 URL -* Metadata - * message\_id 消息 ID - * tool\_name 工具名称 - * tool\_inputs 工具输入 - * tool\_outputs 工具输出 - * tool\_config 工具配置 - * time\_cost 时间成本 - * error 错误信息 - * tool\_parameters 工具参数 - * message\_file\_id 消息文件 ID - * created\_by\_role 创建者角色 - * created\_user\_id 创建者用户 ID \ No newline at end of file +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 云监控 会替换当前选择。 + +编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 + +## Dify 发送的数据 + +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 + +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 + +在阿里云云监控中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充该平台的内置费用字段。 + +### 采集 Agent 调用和内容 + + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + +在应用的追踪设置中，找到 **Agent 数据采集**： + +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 + + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + + +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 + +## 验证新的追踪记录 + +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **云监控** 的 **查看**，打开 ARMS 大模型控制台。 +3. 找到填写的应用名称，再按运行时间定位新的追踪记录，查看其中的子 span。 + +运行结束后，追踪记录可能需要一段时间才会显示。 + +## 故障排查 + + + + 保存配置时会测试采集器是否可访问，不会创建实际追踪记录。确认已选择云监控并启用追踪。在阿里云云监控中，按配置的应用名称找到并打开应用，然后重新运行 Dify 应用。 + + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 + + 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx index fe741d9b6..fe7fe39a9 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,329 +1,74 @@ --- title: 集成 Arize +sidebarTitle: Arize +description: 将 Dify 应用连接至 Arize，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-arize)。 -### Arize 简介 +## 连接应用 -[Arize AX](https://arize.com/products/ax/) 是 [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host) 推出的全功能平台，为 LLM 和 Agent 驱动的应用提供可观测性、在线与离线评估、监控和实验能力。它面向生产环境团队、AI 原生公司和企业，支持托管云与企业自部署两种部署方式。 +在 Arize 的 **Settings** > **API Keys** 中获取 API 密钥和当前 Space ID，详见 [Arize 快速入门](https://arize.com/docs/ax/quickstarts)。确定目标项目名称。如需连接 Phoenix，参考 [Phoenix 集成](/zh/self-host/use-dify/monitor/integrations/integrate-phoenix)。 -如需用于本地开发、实验或单容器自部署的开源方案，可改用 [Phoenix 集成](/zh/self-host/use-dify/monitor/integrations/integrate-phoenix)。 +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Arize** 的 **配置**，填写连接信息： -追踪数据接入后，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [LLM 评估指南](https://arize.com/resources/llm-evaluation/)，了解如何用追踪数据调试故障、评估 Agent 行为、监控模型质量。 +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **API Key** | 是 | 有数据写入权限的 Arize API 密钥。 | +| **Space ID** | 是 | 接收追踪数据的 Arize 空间。 | +| **项目** | 是 | 目标项目名称。 | +| **Endpoint** | 否 | 默认为 `https://otlp.arize.com`。使用自定义采集器时，填写管理员提供的地址。 | -### 配置 Arize +自定义 **Endpoint** 必须支持 OTLP/gRPC。向管理员获取主机名和端口，不要包含 `/v1/traces` 等 HTTP 路径。 -本章节将指引你注册 Arize 并将其集成至 Dify 平台内。 +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Arize 会替换当前选择。 -#### 1. 注册/登录 [Arize](https://app.arize.com/auth/join) +编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将 **API Key** 和 **Space ID** 留空即可保留原值；如果更改端点，则需重新填写这两项。 -### 2. 获取 Arize API 密钥 +## Dify 发送的数据 -从右上角的用户菜单中获取 Arize API 密钥。点击 **API Key**，然后点击 API Key 进行复制： +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 - - ![](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) - +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 -### 3. 集成 Arize 与 Dify +在 Arize 中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充 Arize 的内置费用字段。 -在 Dify 应用中配置 Arize。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 +### 采集 Agent 调用和内容 - - ![](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) - + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + -点击配置后，将在 Arize 中创建的 **API Key**, **Space ID** 和 **项目名称**粘贴到配置中并保存。 +在应用的追踪设置中，找到 **Agent 数据采集**： - - ![](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) - +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 -成功保存后，你可以在当前页面查看监控状态。 + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + - - ![](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) - +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 -## 监控数据列表 +## 验证新的追踪记录 -### **Workflow/Chatflow 追踪信息** +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **Arize** 的 **查看**。如果快捷链接不可用，直接打开 Arize 空间和项目。 +3. 按运行时间找到新的追踪记录，打开后查看子 span。 -**用于追踪 Workflow 和 Chatflow** +运行结束后，追踪记录可能需要一段时间才会显示。 -| 工作流 | Arize 追踪 | -| ---------------------------------- | -------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | - 放置在元数据中 | -| `workflow_{id}` | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| error | error | -| \[workflow] | tags | -| conversation_id/none for workflow | conversation_id in metadata | +## 故障排查 -**工作流追踪信息** + + + 保存配置时会测试采集器是否可访问，不会创建实际追踪记录。确认已选择 Arize 并启用追踪。在 Arize 中打开配置的空间和项目，然后重新运行应用。 -- workflow_id - 工作流唯一标识符 -- conversation_id - 对话 ID -- workflow_run_id - 当前运行的 ID -- tenant_id - 租户 ID -- elapsed_time - 当前运行所用时间 -- status - 运行状态 -- version - 工作流版本 -- total_tokens - 当前运行使用的总令牌数 -- file_list - 处理的文件列表 -- triggered_from - 触发当前运行的来源 -- workflow_run_inputs - 当前运行的输入数据 -- workflow_run_outputs - 当前运行的输出数据 -- error - 当前运行期间遇到的错误 -- query - 运行期间使用的查询 -- workflow_app_log_id - Workflow 应用日志 ID -- message_id - 关联的消息 ID -- start_time - 运行开始时间 -- end_time - 运行结束时间 -- workflow node executions - 工作流节点执行信息 -- 元数据 - - workflow_id - 工作流唯一标识符 - - conversation_id - 对话 ID - - workflow_run_id - 当前运行的 ID - - tenant_id - 租户 ID - - elapsed_time - 当前运行所用时间 - - status - 运行状态 - - version - 工作流版本 - - total_tokens - 当前运行使用的总令牌数 - - file_list - 处理的文件列表 - - triggered_from - 触发当前运行的来源 + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问 gRPC 采集器。让管理员检查采集器的主机名、端口和网络访问权限。填写可访问的服务器地址，不支持 `localhost` 等回环地址。 + + -#### **消息追踪信息** - -**用于追踪 LLM 相关对话** - -| 聊天 | Arize LLM | -| ------------------------------- | --------------------------- | -| message_id | id | -| user_session_id | - 放置在元数据中 | -| "llm" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| \["message", conversation_mode] | tags | -| conversation_id | conversation_id in metadata | - -**消息追踪信息** - -- message_id - 消息 ID -- message_data - 消息数据 -- user_session_id - 用户会话 ID -- conversation_model - 对话模式 -- message_tokens - 消息中的令牌数 -- answer_tokens - 答案中的令牌数 -- total_tokens - 消息和答案中的总令牌数 -- error - 错误信息 -- inputs - 输入数据 -- outputs - 输出数据 -- file_list - 处理的文件列表 -- start_time - 开始时间 -- end_time - 结束时间 -- message_file_data - 与消息关联的文件数据 -- conversation_mode - 对话模式 -- 元数据 - - conversation_id - 对话 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 消息是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **审核追踪信息** - -**用于追踪对话审核** - -| 审核 | Arize Tool | -| -------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["moderation"]| tags | - -**审核追踪信息** - -- message_id - 消息 ID -- user_id - 用户 ID -- workflow_app_log_id - Workflow 应用日志 ID -- inputs - 审核输入数据 -- message_data - 消息数据 -- flagged - 内容是否被标记需要注意 -- action - 采取的具体行动 -- preset_response - 预设响应 -- start_time - 审核开始时间 -- end_time - 审核结束时间 -- 元数据 - - message_id - 消息 ID - - action - 采取的具体行动 - - preset_response - 预设响应 - -#### **建议问题追踪信息** - -**用于追踪建议问题** - -| 建议问题 | Arize LLM | -| --------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "suggested_question" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["suggested_question"]| tags | - -**消息追踪信息** - -- message_id - 消息 ID -- message_data - 消息数据 -- inputs - 输入内容 -- outputs - 输出内容 -- start_time - 开始时间 -- end_time - 结束时间 -- total_tokens - 令牌数量 -- status - 消息状态 -- error - 错误信息 -- from_account_id - 发送账户的 ID -- agent_based - 是否基于代理 -- from_source - 消息来源 -- model_provider - 模型供应商 -- model_id - 模型 ID -- suggested_question - 建议问题 -- level - 状态级别 -- status_message - 状态消息 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **数据集检索追踪信息** - -**用于追踪知识库检索** - -| 数据集检索 | Arize Retriever | -| ------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "dataset_retrieval" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["dataset_retrieval"]| tags | -| message_id | parent_run_id | - -**数据集检索追踪信息** - -- message_id - 消息 ID -- inputs - 输入内容 -- documents - 文档数据 -- start_time - 开始时间 -- end_time - 结束时间 -- message_data - 消息数据 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **工具追踪信息** - -**用于追踪工具调用** - -| 工具 | Arize Tool | -| -------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["tool", tool_name] | tags | - -#### **工具追踪信息** - -- message_id - 消息 ID -- tool_name - 工具名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tool_inputs - 工具输入 -- tool_outputs - 工具输出 -- message_data - 消息数据 -- error - 错误信息（如果有） -- inputs - 消息的输入 -- outputs - 消息的输出 -- tool_config - 工具配置 -- time_cost - 时间消耗 -- tool_parameters - 工具参数 -- file_url - 关联文件的 URL -- 元数据 - - message_id - 消息 ID - - tool_name - 工具名称 - - tool_inputs - 工具输入 - - tool_outputs - 工具输出 - - tool_config - 工具配置 - - time_cost - 时间消耗 - - error - 错误信息（如果有） - - tool_parameters - 工具参数 - - message_file_id - 消息文件 ID - - created_by_role - 创建者角色 - - created_user_id - 创建者用户 ID - -#### **生成名称追踪信息** - -**用于追踪对话标题生成** - -| 生成名称 | Arize Tool | -| ---------------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "generate_conversation_name" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["generate_name"] | tags | - -**生成名称追踪信息** - -- conversation_id - 对话 ID -- inputs - 输入数据 -- outputs - 生成的对话名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tenant_id - 租户 ID -- 元数据 - - conversation_id - 对话 ID - - tenant_id - 租户 ID +评估已采集的追踪数据时，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [大语言模型评估指南](https://arize.com/resources/llm-evaluation/)。 diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index 8298dca1a..d2325f362 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,642 +1,77 @@ --- title: 集成 Langfuse +sidebarTitle: Langfuse +description: 将 Dify 应用连接至 Langfuse，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-langfuse)。 -### 什么是 Langfuse +## 连接应用 -Langfuse 是一个开源的大型语言模型工程平台，帮助团队协作调试、分析和迭代他们的应用。 +创建 Langfuse 项目，在 **Project Settings** > **API Keys** 中获取 [API 密钥](https://langfuse.com/faq/all/where-are-langfuse-api-keys)。使用 Langfuse Cloud 时，选择 [所在区域的基础 URL](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url)，不要包含 `/api/public` 后缀。自部署实例的基础 URL 可向其管理员获取。 - - 介绍 Langfuse: [https://langfuse.com/](https://langfuse.com/) - +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Langfuse** 的 **配置**，填写连接信息： -### 如何配置 Langfuse +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **密钥** | 是 | 项目的密钥。 | +| **公钥** | 是 | 与密钥配套的公钥。 | +| **Host** | 是 | Langfuse 实例的 HTTP(S) 基础 URL。 | -1. 在[官方网站](https://langfuse.com/)注册并登录 Langfuse -2. 在 Langfuse 中创建一个项目。登录后，点击主页上的 **New** 来创建你自己的项目。该 **项目**将用于与 Dify 中的 **应用**关联，以进行数据监控。 + +此集成需要通过 Langfuse 的旧版接收 API `/api/public/ingestion` 接收追踪数据。使用 `events_only` 模式的 Langfuse v4 部署无法接收这些数据。接入前，与 Langfuse 管理员核对 [Langfuse 的数据接收兼容性](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api)。 + - - ![在 Langfuse 中创建一个项目](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) - +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Langfuse 会替换当前选择。 -编辑项目名称。 +编辑配置时，已保存的凭据不会显示。如果 **Host** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 - - ![在 Langfuse 中创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) - +## Dify 发送的数据 -3. 创建项目 API 凭据。在项目的左侧栏中，点击 **Settings** 打开设置。 +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 - - ![创建项目 API 凭据](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) - +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 -在设置中，点击 **Create API Keys** 来创建项目 API 凭据。 +在 Langfuse 中打开一条 generation 记录，可查看采集到的模型调用输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 - - ![创建项目 API 凭据](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) - +### 采集 Agent 调用和内容 -复制并保存 **Secret Key**、**Public Key** 和 **Host**。 + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + - - ![获取 API 密钥配置](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) - +在应用的追踪设置中，找到 **Agent 数据采集**： -4. 在 Dify 中配置 Langfuse。打开你需要监控的应用，在侧边菜单中打开 **Monitoring**，并在页面上选择 **Tracing app performance**。 +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 - - ![配置 Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) - + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + -点击配置后，将在 Langfuse 中创建的 **Secret Key, Public Key, Host** 粘贴到配置中并保存。 +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 - - ![配置 Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) - +## 验证新的追踪记录 -成功保存后，你可以在当前页面查看状态。如果显示为已启动，则正在被监控。 +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **Langfuse** 的 **查看**，打开配置的项目。 +3. 按运行时间找到新的追踪记录，打开后查看模型 generation 记录或节点 span。 - - ![查看配置状态](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) - +运行结束后，追踪记录可能需要一段时间才会显示。 -### 在 Langfuse 中查看监控数据 +## 故障排查 -配置完成后，可以在 Langfuse 中查看 Dify 应用的调试或生产数据。 + + + 保存配置时会检查项目访问权限。确认已选择 Langfuse 并启用追踪，然后重新运行应用，在同一项目中查找。 - - ![](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) - + 让管理员检查 worker 日志中的数据接收错误，并确认 Langfuse 能通过 `/api/public/ingestion` 接收数据。如果仍找不到新运行的追踪记录，还需检查 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 - - ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) - + 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + -### 监控数据列表 - -#### 跟踪 Workflow 和 Chatflow 的信息 - -**跟踪 Workflow 和 Chatflow** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WorkflowLangFuse Trace
workflow\_app\_log\_id/workflow\_run\_idid
user\_session\_iduser\_id
{"workflow_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
Model token consumptionusage
metadatametadata
errorlevel
errorstatus\_message
\[workflow]tags
\["message", conversation\_mode]session\_id
conversion\_idparent\_observation\_id
-**工作流跟踪信息** - -* workflow\_id - 工作流的唯一 ID -* conversation\_id - 对话 ID -* workflow\_run\_id - 此运行时的工作流 ID -* tenant\_id - 租户 ID -* elapsed\_time - 此运行时的经过时间 -* status - 运行时状态 -* version - 工作流版本 -* total\_tokens - 此运行时使用的总标记数 -* file\_list - 处理文件的列表 -* triggered\_from - 触发此运行时的来源 -* workflow\_run\_inputs - 此工作流的输入 -* workflow\_run\_outputs - 此工作流的输出 -* error - 错误信息 -* query - 运行时使用的查询 -* workflow\_app\_log\_id - Workflow 应用日志 ID -* message\_id - 相关消息 ID -* start\_time - 此运行时的开始时间 -* end\_time - 此运行时的结束时间 -* workflow node executions - 工作流节点运行时信息 -* 元数据 - * workflow\_id - 工作流的唯一 ID - * conversation\_id - 对话 ID - * workflow\_run\_id - 此运行时的工作流 ID - * tenant\_id - 租户 ID - * elapsed\_time - 此运行时的经过时间 - * status - 操作状态 - * version - 工作流版本 - * total\_tokens - 此运行时使用的总标记数 - * file\_list - 处理文件的列表 - * triggered\_from - 触发此运行时的来源 - -#### 消息跟踪信息 - -**用于跟踪大型语言模型对话** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MessageLangFuse Generation/Trace
message\_idid
user\_session\_iduser\_id
{"message_{id}"}name
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
Model token consumptionusage
metadatametadata
errorlevel
errorstatus\_message
\["message", conversation\_mode]tags
conversation\_idsession\_id
conversion\_idparent\_observation\_id
-**消息跟踪信息** - -* message\_id - 消息 ID -* message\_data - 消息数据 -* user\_session\_id - 用户会话 ID -* conversation\_model - 对话模型 -* message\_tokens - 消息标记数 -* answer\_tokens - 回答标记数 -* total\_tokens - 消息和回答的总标记数 -* error - 错误信息 -* inputs - 输入数据 -* outputs - 输出数据 -* file\_list - 处理文件的列表 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_file\_data - 相关文件数据的消息 -* conversation\_mode - 对话模式 -* 元数据 - * conversation\_id - 对话 ID - * ls\_provider - 模型供应商 - * ls\_model\_name - 模型 ID - * status - 消息状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户的 ID - * agent\_based - 是否基于 Agent - * workflow\_run\_id - 此运行时的工作流 ID - * from\_source - 消息来源 - * message\_id - 消息 ID - -#### 审核跟踪信息 - -**用于跟踪对话审核** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModerationLangFuse Generation/Trace
user\_iduser\_id
moderationname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[moderation]tags
message\_idparent\_observation\_id
-**消息跟踪信息** - -* message\_id - 消息 ID -* user\_id - 用户 ID -* workflow\_app\_log\_id - Workflow 应用日志 ID -* inputs - 审核输入数据 -* message\_data - 消息数据 -* flagged - 是否标记为关注 -* action - 实施的具体动作 -* preset\_response - 预设响应 -* start\_time - 审核开始时间 -* end\_time - 审核结束时间 -* 元数据 - * message\_id - 消息 ID - * action - 实施的具体动作 - * preset\_response - 预设响应 - -#### 建议问题跟踪信息 - -**用于跟踪建议问题** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Suggested QuestionLangFuse Generation/Trace
user\_iduser\_id
suggested\_questionname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[suggested\_question]tags
message\_idparent\_observation\_id
-**消息跟踪信息** - -* message\_id - 消息 ID -* message\_data - 消息数据 -* inputs - 输入数据 -* outputs - 输出数据 -* start\_time - 开始时间 -* end\_time - 结束时间 -* total\_tokens - 总标记数 -* status - 消息状态 -* error - 错误信息 -* from\_account\_id - 发送账户 ID -* agent\_based - 是否基于 Agent -* from\_source - 消息来源 -* model\_provider - 模型供应商 -* model\_id - 模型 ID -* suggested\_question - 建议问题 -* level - 状态级别 -* status\_message - 消息状态 -* 元数据 - * message\_id - 消息 ID - * ls\_provider - 模型供应商 - * ls\_model\_name - 模型 ID - * status - 消息状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户 ID - * workflow\_run\_id - 此运行时的工作流 ID - * from\_source - 消息来源 - -#### 数据集检索跟踪信息 - -**用于跟踪知识库检索** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Dataset RetrievalLangFuse Generation/Trace
user\_iduser\_id
dataset\_retrievalname
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[dataset\_retrieval]tags
message\_idparent\_observation\_id
-**数据集检索跟踪信息** - -* message\_id - 消息 ID -* inputs - 输入消息 -* documents - 文档数据 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_data - 消息数据 -* 元数据 - * message\_id - 消息 ID - * ls\_provider - 模型供应商 - * ls\_model\_name - 模型 ID - * status - 模型状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户的 ID - * agent\_based - 是否基于 Agent - * workflow\_run\_id - 此运行时的工作流 ID - * from\_source - 消息来源 - -#### 工具跟踪信息 - -**用于跟踪工具调用** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolLangFuse Generation/Trace
user\_iduser\_id
tool\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\["tool", tool\_name]tags
message\_idparent\_observation\_id
-**工具跟踪信息** - -* message\_id - 消息 ID -* tool\_name - 工具名称 -* start\_time - 开始时间 -* end\_time - 结束时间 -* tool\_inputs - 工具输入 -* tool\_outputs - 工具输出 -* message\_data - 消息数据 -* error - 错误信息（如果存在） -* inputs - 消息输入 -* outputs - 消息输出 -* tool\_config - 工具配置 -* time\_cost - 时间消耗 -* tool\_parameters - 工具参数 -* file\_url - 相关文件的 URL -* 元数据 - * message\_id - 消息 ID - * tool\_name - 工具名称 - * tool\_inputs - 工具输入 - * tool\_outputs - 工具输出 - * tool\_config - 工具配置 - * time\_cost - 时间消耗 - * error - 错误信息 - * tool\_parameters - 工具参数 - * message\_file\_id - 消息文件 ID - * created\_by\_role - 创建者角色 - * created\_user\_id - 创建者用户 ID - -#### 生成名称跟踪 - -**用于跟踪对话标题生成** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Generate NameLangFuse Generation/Trace
user\_iduser\_id
generate\_namename
start\_timestart\_time
end\_timeend\_time
inputsinput
outputsoutput
metadatametadata
\[generate\_name]tags
-**生成名称跟踪信息** - -* conversation\_id - 对话 ID -* inputs - 输入数据 -* outputs - 生成的会话名称 -* start\_time - 开始时间 -* end\_time - 结束时间 -* tenant\_id - 租户 ID -* 元数据 - * conversation\_id - 对话 ID - * tenant\_id - 租户 ID - -### Langfuse 提示词管理 - -[Langfuse 提示词管理插件](https://github.com/gao-ai-com/dify-plugin-langfuse)（社区维护）让你可以在 Dify 应用中使用 [Langfuse 中管理和版本化的提示词](https://langfuse.com/docs/prompt-management/get-started)，增强你的大型语言模型应用开发工作流。主要功能包括： - -- **获取提示词**：获取在 Langfuse 中管理的特定提示词。 -- **搜索提示词**：使用各种过滤器在 Langfuse 中搜索提示词。 -- **更新提示词**：在 Langfuse 中创建提示词的新版本，并设置标签/标签。 - -此集成简化了管理和版本化提示词的过程，有助于更高效的开发和迭代周期。你可以在[这里](https://github.com/gao-ai-com/dify-plugin-langfuse)找到插件和安装说明。 +如需使用 Langfuse 中管理的提示词，参考社区维护的 [Langfuse 提示词管理插件](https://github.com/gao-ai-com/dify-plugin-langfuse)，了解安装和使用方法。 diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index e08caad52..2e3d16fd1 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,388 +1,73 @@ --- title: 集成 LangSmith +sidebarTitle: LangSmith +description: 将 Dify 应用连接至 LangSmith，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-langsmith)。 -### LangSmith 简介 +## 连接应用 -LangSmith 是一个用于构建生产级 LLM 应用的平台，它用于开发、协作、测试、部署和监控 LLM 应用。 +获取一个 [LangSmith API 密钥](https://docs.langchain.com/langsmith/create-account-api-key)，确保它有权读取目标工作空间中的项目并发送追踪数据。确定要使用的项目名称，填写时保持完全一致。 - -LangSmith [官网介绍](https://www.langchain.com/langsmith) - +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **LangSmith** 的 **配置**，填写连接信息： -### 配置 LangSmith +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **API Key** | 是 | 有权读取项目和写入追踪数据的密钥。 | +| **项目** | 是 | 项目名称。如果项目不存在，LangSmith 会在收到第一条追踪数据时创建。 | +| **Endpoint** | 否 | 默认为 `https://api.smith.langchain.com`。自定义 API 端点必须使用 HTTPS，并保留所需的路径前缀。 | -本章节将指引你注册 LangSmith 并将其集成至 Dify 平台内。 +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 LangSmith 会替换当前选择。 -#### 1. 注册/登录 [LangSmith](https://www.langchain.com/langsmith) +编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 -#### 2. 创建项目 +## Dify 发送的数据 -在 LangSmith 内创建项目，登录后在主页点击 **New Project** 创建一个自己的项目，**项目**将用于与 Dify 内的**应用**关联进行数据监测。 +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 - - ![在 LangSmith 内创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) - +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 -创建完成之后在 Projects 内可以查看该项目。 +在 LangSmith 中打开一次模型运行，可查看采集到的输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 - - ![在 LangSmith 内查看已创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) - +### 采集 Agent 调用和内容 -#### 3. 创建项目凭据 + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + -创建项目凭据，在左侧边栏内找到项目设置 **Settings**。 +在应用的追踪设置中，找到 **Agent 数据采集**： - - ![项目设置](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) - +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 -点击 **Create API Key**，创建一个项目凭据。 + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + - - ![创建一个项目 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) - +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 -选择 **Personal Access Token** ，用于后续的 API 身份校验。 +## 验证新的追踪记录 - - ![创建一个 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) - +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **LangSmith** 的 **查看**。 +3. 在配置的项目中，按运行时间找到新的运行记录，查看其中的子运行。 -将创建的 API key 复制保存。 +运行结束后，追踪记录可能需要一段时间才会显示。 - - ![复制 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) - +如果第一条追踪数据到达后，点击 **查看** 仍打开项目列表，重新保存配置即可更新项目链接。 -#### 4. 将 LangSmith 集成至 Dify 平台 +## 故障排查 -在 Dify 应用内配置 LangSmith。打开需要监测的应用，在左侧边菜单内打开 **监测**，点击页面内的 **配置。** + + + 保存配置时会检查项目访问权限；新项目在收到第一条追踪数据时才会创建。确认已选择 LangSmith 并启用追踪，然后重新运行应用，按配置中填写的完整项目名称查找。 - - ![配置 LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/b6578e410979cdb9da901aedc94a444d.png) - + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 -点击配置后，将在 LangSmith 内创建的 **API Key** 和 **项目名**粘贴到配置内并保存。 - - - ![配置 LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/27173b2503ca7241b084f7cbd17cdb4c.png) - - - -配置项目名需要与 LangSmith 内设置的项目一致，若项目名不一致，数据同步时 LangSmith 会自动创建一个新的项目。 - - -成功保存后可以在当前页面查看监测状态。 - - - ![查看配置状态](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/a4e9df6427c7914e1eef6af78d71f408.png) - - -### 在 LangSmith 内查看监测数据 - -配置完成后，Dify 内应用的调试或生产数据可以在 LangSmith 查看监测数据。 - - - ![在 Dify 内调试应用](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/a0e7b21d56ecf9313f1bd48913f0a74b.png) - - - - ![在 LangSmith 内查看应用数据](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) - - - - ![在 LangSmith 内查看应用数据](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/c40e522f1ffe9fc50411dd7feaf937ed.png) - - -### 监测数据清单 - -#### Workflow /Chatflow Trace 信息 - -**用于追踪 workflow 以及 chatflow** - -| Workflow | LangSmith Chain | -| ---------------------------------------- | -------------------------- | -| workflow\_app\_log\_id/workflow\_run\_id | id | -| user\_session\_id | -放入 metadata | -| workflow_\{id\} | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| 模型 token 消耗相关 | usage\_metadata | -| metadata | extra | -| error | error | -| \[workflow] | tags | -| "conversation\_id/workflow 时无" | metadata 中的 conversation\_id | -| conversion\_id | parent\_run\_id | - -**Workflow Trace Info** - -* workflow\_id - Workflow 的唯一标识 -* conversation\_id - 对话 ID -* workflow\_run\_id - 此次运行的 ID -* tenant\_id - 租户 ID -* elapsed\_time - 此次运行耗时 -* status - 运行状态 -* version - Workflow 版本 -* total\_tokens - 此次运行使用的 token 总数 -* file\_list - 处理的文件列表 -* triggered\_from - 触发此次运行的来源 -* workflow\_run\_inputs - 此次运行的输入数据 -* workflow\_run\_outputs - 此次运行的输出数据 -* error - 此次运行中发生的错误 -* query - 运行时使用的查询 -* workflow\_app\_log\_id - Workflow 应用日志 ID -* message\_id - 关联的消息 ID -* start\_time - 运行开始时间 -* end\_time - 运行结束时间 -* workflow node executions - workflow 节点运行信息 -* Metadata - * workflow\_id - Workflow 的唯一标识 - * conversation\_id - 对话 ID - * workflow\_run\_id - 此次运行的 ID - * tenant\_id - 租户 ID - * elapsed\_time - 此次运行耗时 - * status - 运行状态 - * version - Workflow 版本 - * total\_tokens - 此次运行使用的 token 总数 - * file\_list - 处理的文件列表 - * triggered\_from - 触发来源 - -#### Message Trace 信息 - -**用于追踪 llm 对话相关** - -| Chat | LangSmith LLM | -| -------------------------------- | -------------------------- | -| message\_id | id | -| user\_session\_id | -放入 metadata | -| "message_\{id\}" | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| 模型 token 消耗相关 | usage\_metadata | -| metadata | extra | -| error | error | -| \["message", conversation\_mode] | tags | -| conversation\_id | metadata 中的 conversation\_id | -| conversion\_id | parent\_run\_id | - -**Message Trace Info** - -* message\_id - 消息 ID -* message\_data - 消息数据 -* user\_session\_id - 用户的 session\_id -* conversation\_model - 对话模式 -* message\_tokens - 消息中的令牌数 -* answer\_tokens - 回答中的令牌数 -* total\_tokens - 消息和回答中的总令牌数 -* error - 错误信息 -* inputs - 输入数据 -* outputs - 输出数据 -* file\_list - 处理的文件列表 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_file\_data - 消息关联的文件数据 -* conversation\_mode - 对话模式 -* Metadata - * conversation\_id - 消息所属对话的 ID - * ls\_provider - 模型提供者 - * ls\_model\_name - 模型 ID - * status - 消息状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户的 ID - * agent\_based - 是否基于代理 - * workflow\_run\_id - 工作流运行 ID - * from\_source - 消息来源 - * message\_id - 消息 ID - -#### Moderation Trace 信息 - -**用于追踪对话审查** - -| Moderation | LangSmith Tool | -| ------------- | --------------- | -| user\_id | -放入 metadata | -| “moderation" | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[moderation] | tags | -| message\_id | parent\_run\_id | - -**Message Trace Info** - -* message\_id - 消息 ID -* user\_id: 用户 id -* workflow\_app\_log\_id workflow\_app\_log\_id -* inputs - 审查的输入数据 -* message\_data - 消息数据 -* flagged - 是否被标记为需要注意的内容 -* action - 执行的具体行动 -* preset\_response - 预设响应 -* start\_time - 审查开始时间 -* end\_time - 审查结束时间 -* Metadata - * message\_id - 消息 ID - * action - 执行的具体行动 - * preset\_response - 预设响应 - -#### Suggested Question Trace 信息 - -**用于追踪建议问题** - -| Suggested Question | LangSmith LLM | -| ---------------------- | --------------- | -| user\_id | -放入 metadata | -| suggested\_question | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[suggested\_question] | tags | -| message\_id | parent\_run\_id | - -**Message Trace Info** - -* message\_id - 消息 ID -* message\_data - 消息数据 -* inputs - 输入的内容 -* outputs - 输出的内容 -* start\_time - 开始时间 -* end\_time - 结束时间 -* total\_tokens - 令牌数量 -* status - 消息状态 -* error - 错误信息 -* from\_account\_id - 发送账户的 ID -* agent\_based - 是否基于代理 -* from\_source - 消息来源 -* model\_provider - 模型提供者 -* model\_id - 模型 ID -* suggested\_question - 建议的问题 -* level - 状态级别 -* status\_message - 状态信息 -* Metadata - * message\_id - 消息 ID - * ls\_provider - 模型提供者 - * ls\_model\_name - 模型 ID - * status - 消息状态 - * from\_end\_user\_id - 发送用户的 ID - * from\_account\_id - 发送账户的 ID - * workflow\_run\_id - 工作流运行 ID - * from\_source - 消息来源 - -#### Dataset Retrieval Trace 信息 - -**用于追踪知识库检索** - -| Dataset Retrieval | LangSmith Retriever | -| --------------------- | ------------------- | -| user\_id | -放入 metadata | -| dataset\_retrieval | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[dataset\_retrieval] | tags | -| message\_id | parent\_run\_id | - -**Dataset Retrieval Trace Info** - -* message\_id - 消息 ID -* inputs - 输入内容 -* documents - 文档数据 -* start\_time - 开始时间 -* end\_time - 结束时间 -* message\_data - 消息数据 -* Metadata - * message\_id 消息 ID - * ls\_provider 模型提供者 - * ls\_model\_name 模型 ID - * status 消息状态 - * from\_end\_user\_id 发送用户的 ID - * from\_account\_id 发送账户的 ID - * agent\_based 是否基于代理 - * workflow\_run\_id 工作流运行 ID - * from\_source 消息来源 - -#### Tool Trace 信息 - -**用于追踪工具调用** - -| Tool | LangSmith Tool | -| --------------------- | --------------- | -| user\_id | -放入 metadata | -| tool\_name | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \["tool", tool\_name] | tags | -| message\_id | parent\_run\_id | - -**Tool Trace Info** - -* message\_id 消息 ID -* tool\_name 工具名称 -* start\_time 开始时间 -* end\_time 结束时间 -* tool\_inputs 工具输入 -* tool\_outputs 工具输出 -* message\_data 消息数据 -* error 错误信息，如果存在 -* inputs 消息的输入内容 -* outputs 消息的回答内容 -* tool\_config 工具配置 -* time\_cost 时间成本 -* tool\_parameters 工具参数 -* file\_url 关联文件的 URL -* Metadata - * message\_id 消息 ID - * tool\_name 工具名称 - * tool\_inputs 工具输入 - * tool\_outputs 工具输出 - * tool\_config 工具配置 - * time\_cost 时间成本 - * error 错误信息 - * tool\_parameters 工具参数 - * message\_file\_id 消息文件 ID - * created\_by\_role 创建者角色 - * created\_user\_id 创建者用户 ID - -#### Generate Name Trace 信息 - -**用于追踪会话标题生成** - -| Generate Name | LangSmith Tool | -| ----------------- | -------------- | -| user\_id | -放入 metadata | -| generate\_name | name | -| start\_time | start\_time | -| end\_time | end\_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[generate\_name] | tags | - -**Generate Name Trace Info** - -* conversation\_id 对话 ID -* inputs 输入数据 -* outputs 生成的会话名称 -* start\_time 开始时间 -* end\_time 结束时间 -* tenant\_id 租户 ID -* Metadata - * conversation\_id 对话 ID - * tenant\_id 租户 ID + 使用内网端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx index 4dcc96c94..c62181e63 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,345 +1,72 @@ --- title: 集成 Opik +sidebarTitle: Opik +description: 将 Dify 应用连接至 Opik，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-opik)。 -## Opik 简介 +## 连接应用 -Opik 是一个开源的 LLM 评估平台，用于评估、测试和监控大型语言模型（LLM）应用。它由 Comet 开发，旨在促进对基于 LLM 的应用进行更直观的协作、测试和监控。 +获取托管版 Opik 的 API 密钥，或使用自建 Opik 实例。账户设置方法详见 [Opik 的 Dify 集成指南](https://www.comet.com/docs/opik/integrations/dify)。使用自建服务器上的指定工作空间时，向管理员确认工作空间名称。 - -如需了解更多详情，请参考 [Opik](https://www.comet.com/site/products/opik/)。 - +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Opik** 的 **配置**，填写连接信息： ---- - -## 开始配置 Opik - -### 1. 注册/登录 [Opik](https://www.comet.com/signup?from=llm) - -### 2. 获取 Opik API 密钥 - -从右上角的用户菜单中获取 Opik API 密钥。点击 **API Key**，然后点击 API Key 进行复制： - - - ![](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) - - -### 3. 集成 Opik 与 Dify - -在 Dify 应用中配置 Opik。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 - - - ![](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) - - -点击配置后，将在 Opik 中创建的 **API Key** 和 **项目名称**粘贴到配置中并保存。 - - - ![](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) - - -成功保存后，你可以在当前页面查看监控状态。 - -## 查看监控数据 - -配置完成后，你可以照常调试或使用 Dify 应用。所有使用历史都可以在 Opik 中监控。 - - - ![](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) - - -当你切换到 Opik 时，可以在仪表板中查看 Dify 应用的详细操作日志。 - - - ![](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) - - -通过 Opik 的详细 LLM 操作日志将帮助你优化 Dify 应用的性能。 - - - ![](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) - - -## 监控数据列表 - -### **Workflow/Chatflow 追踪信息** - -**用于追踪 Workflow 和 Chatflow** - -| 工作流 | Opik 追踪 | -| ---------------------------------- | -------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | - 放置在元数据中 | -| `workflow_{id}` | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| error | error | -| \[workflow] | tags | -| conversation_id/none for workflow | conversation_id in metadata | - -**工作流追踪信息** - -- workflow_id - 工作流唯一标识符 -- conversation_id - 对话 ID -- workflow_run_id - 当前运行的 ID -- tenant_id - 租户 ID -- elapsed_time - 当前运行所用时间 -- status - 运行状态 -- version - 工作流版本 -- total_tokens - 当前运行使用的总令牌数 -- file_list - 处理的文件列表 -- triggered_from - 触发当前运行的来源 -- workflow_run_inputs - 当前运行的输入数据 -- workflow_run_outputs - 当前运行的输出数据 -- error - 当前运行期间遇到的错误 -- query - 运行期间使用的查询 -- workflow_app_log_id - Workflow 应用日志 ID -- message_id - 关联的消息 ID -- start_time - 运行开始时间 -- end_time - 运行结束时间 -- workflow node executions - 工作流节点执行信息 -- 元数据 - - workflow_id - 工作流唯一标识符 - - conversation_id - 对话 ID - - workflow_run_id - 当前运行的 ID - - tenant_id - 租户 ID - - elapsed_time - 当前运行所用时间 - - status - 运行状态 - - version - 工作流版本 - - total_tokens - 当前运行使用的总令牌数 - - file_list - 处理的文件列表 - - triggered_from - 触发当前运行的来源 - -#### **消息追踪信息** - -**用于追踪 LLM 相关对话** - -| 聊天 | Opik LLM | -| ------------------------------- | --------------------------- | -| message_id | id | -| user_session_id | - 放置在元数据中 | -| "llm" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| \["message", conversation_mode] | tags | -| conversation_id | conversation_id in metadata | - -**消息追踪信息** - -- message_id - 消息 ID -- message_data - 消息数据 -- user_session_id - 用户会话 ID -- conversation_model - 对话模式 -- message_tokens - 消息中的令牌数 -- answer_tokens - 答案中的令牌数 -- total_tokens - 消息和答案中的总令牌数 -- error - 错误信息 -- inputs - 输入数据 -- outputs - 输出数据 -- file_list - 处理的文件列表 -- start_time - 开始时间 -- end_time - 结束时间 -- message_file_data - 与消息关联的文件数据 -- conversation_mode - 对话模式 -- 元数据 - - conversation_id - 对话 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 消息是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **审核追踪信息** - -**用于追踪对话审核** - -| 审核 | Opik Tool | -| -------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["moderation"]| tags | - -**审核追踪信息** - -- message_id - 消息 ID -- user_id - 用户 ID -- workflow_app_log_id - Workflow 应用日志 ID -- inputs - 审核输入数据 -- message_data - 消息数据 -- flagged - 内容是否被标记需要注意 -- action - 采取的具体行动 -- preset_response - 预设响应 -- start_time - 审核开始时间 -- end_time - 审核结束时间 -- 元数据 - - message_id - 消息 ID - - action - 采取的具体行动 - - preset_response - 预设响应 - -#### **建议问题追踪信息** +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **API Key** | 托管版 Opik 必填 | 账户的 API 密钥。仅当服务器未启用认证时可留空。 | +| **项目** | 否 | 项目名称；Opik 会在收到第一条追踪数据时创建项目。留空时，Dify 使用 `Default Project`。 | +| **Workspace** | 否 | 已有的工作空间。留空时，Dify 使用账户默认工作空间；对于未启用认证的开源服务器，则使用 `default`。 | +| **Url** | 否 | 默认为 `https://www.comet.com/opik/api/`。自定义 HTTP(S) URL 必须以 `/api/` 结尾。 | -**用于追踪建议问题** +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Opik 会替换当前选择。 -| 建议问题 | Opik LLM | -| --------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "suggested_question" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["suggested_question"]| tags | +编辑配置时，已保存的凭据不会显示。如果 **Url** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 -**消息追踪信息** +## Dify 发送的数据 -- message_id - 消息 ID -- message_data - 消息数据 -- inputs - 输入内容 -- outputs - 输出内容 -- start_time - 开始时间 -- end_time - 结束时间 -- total_tokens - 令牌数量 -- status - 消息状态 -- error - 错误信息 -- from_account_id - 发送账户的 ID -- agent_based - 是否基于代理 -- from_source - 消息来源 -- model_provider - 模型供应商 -- model_id - 模型 ID -- suggested_question - 建议问题 -- level - 状态级别 -- status_message - 状态消息 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 -#### **数据集检索追踪信息** +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 -**用于追踪知识库检索** +在 Opik 中打开一个 LLM span，可查看采集到的模型调用输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 -| 数据集检索 | Opik Retriever | -| ------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "dataset_retrieval" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["dataset_retrieval"]| tags | -| message_id | parent_run_id | +### 采集 Agent 调用和内容 -**数据集检索追踪信息** + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + -- message_id - 消息 ID -- inputs - 输入内容 -- documents - 文档数据 -- start_time - 开始时间 -- end_time - 结束时间 -- message_data - 消息数据 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 +在应用的追踪设置中，找到 **Agent 数据采集**： -#### **工具追踪信息** +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 -**用于追踪工具调用** + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + -| 工具 | Opik Tool | -| -------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["tool", tool_name] | tags | +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 -#### **工具追踪信息** +## 验证新的追踪记录 -- message_id - 消息 ID -- tool_name - 工具名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tool_inputs - 工具输入 -- tool_outputs - 工具输出 -- message_data - 消息数据 -- error - 错误信息（如果有） -- inputs - 消息的输入 -- outputs - 消息的输出 -- tool_config - 工具配置 -- time_cost - 时间消耗 -- tool_parameters - 工具参数 -- file_url - 关联文件的 URL -- 元数据 - - message_id - 消息 ID - - tool_name - 工具名称 - - tool_inputs - 工具输入 - - tool_outputs - 工具输出 - - tool_config - 工具配置 - - time_cost - 时间消耗 - - error - 错误信息（如果有） - - tool_parameters - 工具参数 - - message_file_id - 消息文件 ID - - created_by_role - 创建者角色 - - created_user_id - 创建者用户 ID +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **Opik** 的 **查看**。如果链接打开控制台，选择配置的工作空间和项目。 +3. 按运行时间找到新的追踪记录，打开后查看其中的 span。 -#### **生成名称追踪信息** +运行结束后，追踪记录可能需要一段时间才会显示。 -**用于追踪对话标题生成** +## 故障排查 -| 生成名称 | Opik Tool | -| ---------------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "generate_conversation_name" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["generate_name"] | tags | + + + 保存配置时会检查工作空间访问权限；Opik 在收到第一条追踪数据时创建项目。确认已选择 Opik 并启用追踪。在 Opik 中打开配置的工作空间和项目，然后重新运行应用。 -**生成名称追踪信息** + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 -- conversation_id - 对话 ID -- inputs - 输入数据 -- outputs - 生成的对话名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tenant_id - 租户 ID -- 元数据 - - conversation_id - 对话 ID - - tenant_id - 租户 ID + 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index 80eaaa9b1..1fcf075d7 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,379 +1,75 @@ --- title: 集成 Phoenix +sidebarTitle: Phoenix +description: 将 Dify 应用连接至 Phoenix，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-phoenix)。 -### Phoenix 简介 +## 连接应用 -[Arize Phoenix](https://arize.com/phoenix/) 是 [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) 推出的开源平台，基于 OpenTelemetry 构建，为 LLM 工作流和 Agent 提供可观测性、评估、提示工程和实验能力。 +选择 Dify 服务能访问的 Phoenix 实例，自部署或 Phoenix Cloud 均可。如果实例启用了认证，获取一个有权读取项目并发送追踪数据的 [API 密钥](https://arize.com/docs/phoenix/settings/api-keys)。如需连接 Arize，参考 [Arize 集成](/zh/self-host/use-dify/monitor/integrations/integrate-arize)。 -开发阶段可在本地运行 Phoenix，也可在自有基础设施上以单容器方式自部署，或使用 Arize 托管的 [Phoenix Cloud](#配置-phoenix-cloud)。 +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Phoenix** 的 **配置**，填写连接信息： -如需面向生产环境团队、AI 原生公司和企业的全功能平台，可改用 [Arize 集成](/zh/self-host/use-dify/monitor/integrations/integrate-arize) 接入 [Arize AX](https://arize.com/products/ax/)。 +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **API Key** | 启用认证时必填 | 实例或 Phoenix Cloud 空间的密钥。服务器未启用认证时留空。 | +| **项目** | 是 | 目标项目名称。 | +| **Endpoint** | 否 | Phoenix 基础 URL。将默认值 `https://app.phoenix.arize.com` 替换为 Cloud 空间或自部署实例的 URL，并保留路径前缀。 | -追踪数据接入后，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [LLM 评估指南](https://arize.com/resources/llm-evaluation/)，了解如何用追踪数据调试故障、评估 Agent 行为、监控模型质量。 +使用 Phoenix Cloud 时，复制空间地址，例如 `https://app.phoenix.arize.com/s/`。获取位置详见 [查找 Phoenix 端点](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint)。填写基础 URL 时不要包含 `/v1/traces`，Dify 会自动添加该路径。 -### 配置 Phoenix +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Phoenix 会替换当前选择。 -本章节将指引你注册 Phoenix 并将其集成至 Dify 平台内。 +编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 -#### 1. 注册/登录 [Phoenix](https://app.arize.com/auth/phoenix/signup) +## Dify 发送的数据 -### 2. 获取 Phoenix API 密钥 +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 -从右上角的用户菜单中获取 Phoenix API 密钥。点击 **API Key**，然后点击 API Key 进行复制： +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 - - ![](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) - +在 Phoenix 中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充 Phoenix 的内置费用字段。 -### 3. 集成 Phoenix 与 Dify +### 采集 Agent 调用和内容 -在 Dify 应用中配置 Phoenix。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + - - ![](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - +在应用的追踪设置中，找到 **Agent 数据采集**： -点击配置后，将在 Phoenix 中创建的 **API Key** 和 **项目名称**粘贴到配置中并保存。 +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 - - ![](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + -成功保存后，你可以在当前页面查看监控状态。 +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 - - ![](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - +## 验证新的追踪记录 -### 配置 Phoenix Cloud +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **Phoenix** 的 **查看**，打开配置的项目。 +3. 按运行时间找到新的追踪记录，打开后查看子 span。 -本章节将指引你注册 Phoenix Cloud 并将其集成至 Dify 平台内。 +运行结束后，追踪记录可能需要一段时间才会显示。 -#### 1. 注册/登录 [Phoenix Cloud](https://app.arize.com/auth/phoenix/signup) +## 故障排查 -### 2. 创建你的 Phoenix 空间 + + + 保存配置时会确认项目读取权限，不会发送追踪数据。确认已选择 Phoenix 并启用追踪，然后重新运行应用，在配置的项目中查找。 -你可以在右上角的用户菜单中创建 Phoenix 空间。点击 创建空间，然后为你的空间提供一个唯一的 URL 标识符： + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 - - ![](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) - + 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + -保存成功后，你可以在概览页面查看空间的状态。 - - - ![](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) - - -### 3. 创建你的 Phoenix API 密钥 - -启动空间后，你可以在左下角的用户菜单中点击 设置 来创建 Phoenix API 密钥。点击 系统密钥，然后为你的 API 密钥命名： - - - ![](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) - - -### 4. 集成 Phoenix Cloud 与 Dify - -在 Dify 应用中配置 Phoenix。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 - - - ![](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) - - -点击配置后，粘贴从 Phoenix Cloud 中获取的 API 密钥、项目名称 和 空间主机名 到配置项中并保存。 - - - ![](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) - - -成功保存后，你可以在当前页面查看监控状态。 - - - ![](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) - - -## 监控数据列表 - -### **Workflow/Chatflow 追踪信息** - -**用于追踪 Workflow 和 Chatflow** - -| 工作流 | Phoenix 追踪 | -| ---------------------------------- | -------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | - 放置在元数据中 | -| `workflow_{id}` | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| error | error | -| \[workflow] | tags | -| conversation_id/none for workflow | conversation_id in metadata | - -**工作流追踪信息** - -- workflow_id - 工作流唯一标识符 -- conversation_id - 对话 ID -- workflow_run_id - 当前运行的 ID -- tenant_id - 租户 ID -- elapsed_time - 当前运行所用时间 -- status - 运行状态 -- version - 工作流版本 -- total_tokens - 当前运行使用的总令牌数 -- file_list - 处理的文件列表 -- triggered_from - 触发当前运行的来源 -- workflow_run_inputs - 当前运行的输入数据 -- workflow_run_outputs - 当前运行的输出数据 -- error - 当前运行期间遇到的错误 -- query - 运行期间使用的查询 -- workflow_app_log_id - Workflow 应用日志 ID -- message_id - 关联的消息 ID -- start_time - 运行开始时间 -- end_time - 运行结束时间 -- workflow node executions - 工作流节点执行信息 -- 元数据 - - workflow_id - 工作流唯一标识符 - - conversation_id - 对话 ID - - workflow_run_id - 当前运行的 ID - - tenant_id - 租户 ID - - elapsed_time - 当前运行所用时间 - - status - 运行状态 - - version - 工作流版本 - - total_tokens - 当前运行使用的总令牌数 - - file_list - 处理的文件列表 - - triggered_from - 触发当前运行的来源 - -#### **消息追踪信息** - -**用于追踪 LLM 相关对话** - -| 聊天 | Phoenix LLM | -| ------------------------------- | --------------------------- | -| message_id | id | -| user_session_id | - 放置在元数据中 | -| "llm" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| Model token consumption | usage_metadata | -| metadata | metadata | -| \["message", conversation_mode] | tags | -| conversation_id | conversation_id in metadata | - -**消息追踪信息** - -- message_id - 消息 ID -- message_data - 消息数据 -- user_session_id - 用户会话 ID -- conversation_model - 对话模式 -- message_tokens - 消息中的令牌数 -- answer_tokens - 答案中的令牌数 -- total_tokens - 消息和答案中的总令牌数 -- error - 错误信息 -- inputs - 输入数据 -- outputs - 输出数据 -- file_list - 处理的文件列表 -- start_time - 开始时间 -- end_time - 结束时间 -- message_file_data - 与消息关联的文件数据 -- conversation_mode - 对话模式 -- 元数据 - - conversation_id - 对话 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 消息是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **审核追踪信息** - -**用于追踪对话审核** - -| 审核 | Phoenix Tool | -| -------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["moderation"]| tags | - -**审核追踪信息** - -- message_id - 消息 ID -- user_id - 用户 ID -- workflow_app_log_id - Workflow 应用日志 ID -- inputs - 审核输入数据 -- message_data - 消息数据 -- flagged - 内容是否被标记需要注意 -- action - 采取的具体行动 -- preset_response - 预设响应 -- start_time - 审核开始时间 -- end_time - 审核结束时间 -- 元数据 - - message_id - 消息 ID - - action - 采取的具体行动 - - preset_response - 预设响应 - -#### **建议问题追踪信息** - -**用于追踪建议问题** - -| 建议问题 | Phoenix LLM | -| --------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "suggested_question" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["suggested_question"]| tags | - -**消息追踪信息** - -- message_id - 消息 ID -- message_data - 消息数据 -- inputs - 输入内容 -- outputs - 输出内容 -- start_time - 开始时间 -- end_time - 结束时间 -- total_tokens - 令牌数量 -- status - 消息状态 -- error - 错误信息 -- from_account_id - 发送账户的 ID -- agent_based - 是否基于代理 -- from_source - 消息来源 -- model_provider - 模型供应商 -- model_id - 模型 ID -- suggested_question - 建议问题 -- level - 状态级别 -- status_message - 状态消息 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **数据集检索追踪信息** - -**用于追踪知识库检索** - -| 数据集检索 | Phoenix Retriever | -| ------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "dataset_retrieval" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["dataset_retrieval"]| tags | -| message_id | parent_run_id | - -**数据集检索追踪信息** - -- message_id - 消息 ID -- inputs - 输入内容 -- documents - 文档数据 -- start_time - 开始时间 -- end_time - 结束时间 -- message_data - 消息数据 -- 元数据 - - message_id - 消息 ID - - ls_provider - 模型供应商 - - ls_model_name - 模型 ID - - status - 消息状态 - - from_end_user_id - 发送用户的 ID - - from_account_id - 发送账户的 ID - - agent_based - 是否基于代理 - - workflow_run_id - 工作流运行 ID - - from_source - 消息来源 - -#### **工具追踪信息** - -**用于追踪工具调用** - -| 工具 | Phoenix Tool | -| -------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["tool", tool_name] | tags | - -#### **工具追踪信息** - -- message_id - 消息 ID -- tool_name - 工具名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tool_inputs - 工具输入 -- tool_outputs - 工具输出 -- message_data - 消息数据 -- error - 错误信息（如果有） -- inputs - 消息的输入 -- outputs - 消息的输出 -- tool_config - 工具配置 -- time_cost - 时间消耗 -- tool_parameters - 工具参数 -- file_url - 关联文件的 URL -- 元数据 - - message_id - 消息 ID - - tool_name - 工具名称 - - tool_inputs - 工具输入 - - tool_outputs - 工具输出 - - tool_config - 工具配置 - - time_cost - 时间消耗 - - error - 错误信息（如果有） - - tool_parameters - 工具参数 - - message_file_id - 消息文件 ID - - created_by_role - 创建者角色 - - created_user_id - 创建者用户 ID - -#### **生成名称追踪信息** - -**用于追踪对话标题生成** - -| 生成名称 | Phoenix Tool | -| ---------------------------- | ----------------- | -| user_id | - 放置在元数据中 | -| "generate_conversation_name" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | metadata | -| \["generate_name"] | tags | - -**生成名称追踪信息** - -- conversation_id - 对话 ID -- inputs - 输入数据 -- outputs - 生成的对话名称 -- start_time - 开始时间 -- end_time - 结束时间 -- tenant_id - 租户 ID -- 元数据 - - conversation_id - 对话 ID - - tenant_id - 租户 ID +评估已采集的追踪数据时，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [大语言模型评估指南](https://arize.com/resources/llm-evaluation/)。 diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx index a5e9af02e..70d3d35b0 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -1,348 +1,75 @@ --- title: 集成 W&B Weave -description: 通过 W&B Weave 实现 Dify 应用的 LLM 可观测性，将追踪数据发送至 W&B Weave +sidebarTitle: W&B Weave +description: 将 Dify 应用的追踪数据发送至 W&B Weave，实现大语言模型可观测性 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-weave)。 - - **前提条件**：Dify v1.3.1 或更高版本。 - +## 连接应用 -### 什么是 W&B Weave +配置 Dify 前，先创建一个 [W&B 项目](https://docs.wandb.ai/models/track/project-page#create-a-project)，确保 [API 密钥](https://wandb.ai/authorize) 有该项目的写入权限。团队项目的 **Entity** 填写所属团队。 -Weights & Biases (W&B) Weave 是一个用于跟踪、实验、评估、部署和改进基于 LLM 的应用的框架。Weave 专为灵活性和可扩展性而设计，支持 LLM 应用开发工作流的每个阶段。 +在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Weave** 的 **配置**，填写连接信息： - - 更多详情，请参考 [Weave](https://docs.wandb.ai/weave)。 - +| 字段 | 是否必填 | 填写内容 | +|:------|:---------|:------| +| **API Key** | 是 | W&B API 密钥。 | +| **项目** | 是 | 已存在且有写入权限的项目。也可在此填写 `entity/project`，将 **Entity** 留空。 | +| **Entity** | 否 | W&B 团队或用户。留空时，Dify 使用 API 密钥对应的默认 entity。 | +| **Endpoint** | 否 | Weave 追踪服务器地址。默认为 `https://trace.wandb.ai`，必须使用 HTTPS。 | +| **Host** | 否 | W&B API 服务器地址。默认为 `https://api.wandb.ai`，支持 HTTP(S)。 | -### 如何配置 Weave +使用自定义部署时，向管理员获取追踪服务器的 **Endpoint** 和 W&B API 的 **Host**，并保留其提供的路径前缀。 -#### 1. 注册/登录 +确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Weave 会替换当前选择。 -前往 [W&B Weave](https://wandb.ai/signup) 注册/登录。创建一个 Weights & Biases (W&B) 账户，并在[此处](https://wandb.ai/authorize)复制 API 密钥。 +编辑配置时，已保存的凭据不会显示。如果 **Host** 和 **Endpoint** 均不变，将凭据留空即可保留原值；如果更改任一地址，则需重新填写凭据。 -#### 2. 将 W&B Weave 与 Dify 集成 +## Dify 发送的数据 -在 Dify 应用中配置 Weave。打开需要监控的应用，在侧边菜单中打开 **监控**，在页面上选择 **跟踪应用性能**。 +一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 - - ![在 Dify 应用中配置 Weave](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) - +在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 -点击配置后，粘贴 **API 密钥** 和**项目名称**，指定 **W&B 实体**（可选，默认为你的用户名）到配置中并保存。 +在 Weave 中打开一次模型调用，可查看采集到的输入和输出。如果有 token 数量数据，会按模型显示在该调用的用量信息中。Dify 不会填充 Weave 的内置费用字段。 - - ![](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) - +### 采集 Agent 调用和内容 -成功保存后，你可以在当前页面查看监控状态。 + +Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + - - ![成功保存后，你可以在当前页面查看监控状态](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) - +在应用的追踪设置中，找到 **Agent 数据采集**： -### 在 Weave 中查看监控数据 +- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 +- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 -配置完成后，Dify 内应用的调试或生产数据可以在 Weave 中进行监控。 + +这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 + - - ![](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) - +新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 -当你切换到 Weave 时，可以在仪表板中查看 Dify 应用的详细操作日志。 +## 验证新的追踪记录 - - ![](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) - +1. 在 Dify 应用中发起一次新请求，等待运行完成。 +2. 在 **追踪应用性能** 中，点击 **Weave** 的 **查看**，打开配置的项目。 +3. 按运行时间找到新的调用记录，打开后查看其中的子调用。 -通过 Weave 获取的详细 LLM 操作日志将帮助你优化 Dify 应用的性能。 +运行结束后，追踪记录可能需要一段时间才会显示。 -### 监控数据列表 +## 故障排查 -#### **Workflow/Chatflow 追踪信息** + + + 保存配置时会检查项目是否存在、是否有写入权限，以及追踪服务器是否可访问。确认已选择 Weave 并启用追踪。在 Weave 中打开配置的 entity 和项目，然后重新运行应用。 -**用于追踪 Workflow 和 Chatflow** + 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 + + + Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 -| 工作流 | Weave 追踪 | -| ---------------------------------------- | ---------------------------- | -| workflow_app_log_id/workflow_run_id | id | -| user_session_id | 放置在元数据中 | -| workflow_\{id\} | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| 模型令牌消耗 | usage_metadata | -| metadata | extra | -| error | error | -| workflow | tags | -| "conversation_id/none for workflow" | 元数据中的 conversation_id | -| conversion_id | parent_run_id | - -**工作流追踪信息** - -* workflow_id - 工作流的唯一标识符 -* conversation_id - 对话 ID -* workflow_run_id - 当前运行的 ID -* tenant_id - 租户 ID -* elapsed_time - 当前运行所花费的时间 -* status - 运行状态 -* version - 工作流版本 -* total_tokens - 当前运行中使用的总令牌数 -* file_list - 处理的文件列表 -* triggered_from - 触发当前运行的来源 -* workflow_run_inputs - 当前运行的输入数据 -* workflow_run_outputs - 当前运行的输出数据 -* error - 当前运行期间遇到的错误 -* query - 运行期间使用的查询 -* workflow_app_log_id - Workflow 应用日志 ID -* message_id - 关联的消息 ID -* start_time - 运行的开始时间 -* end_time - 运行的结束时间 -* workflow node executions - 工作流节点执行的信息 -* 元数据 - * workflow_id - 工作流的唯一标识符 - * conversation_id - 对话 ID - * workflow_run_id - 当前运行的 ID - * tenant_id - 租户 ID - * elapsed_time - 当前运行所花费的时间 - * status - 运行状态 - * version - 工作流版本 - * total_tokens - 当前运行中使用的总令牌数 - * file_list - 处理的文件列表 - * triggered_from - 触发当前运行的来源 - -#### **消息追踪信息** - -**用于追踪与 LLM 相关的对话** - -| 聊天 | Weave 追踪 | -| -------------------------------- | ----------------------------- | -| message_id | id | -| user_session_id | 放置在元数据中 | -| "message_\{id\}" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| 模型令牌消耗 | usage_metadata | -| metadata | extra | -| error | error | -| "message", conversation_mode | tags | -| conversation_id | 元数据中的 conversation_id | -| conversion_id | parent_run_id | - -**消息追踪信息** - -* message_id - 消息 ID -* message_data - 消息数据 -* user_session_id - 用户会话 ID -* conversation_model - 对话模式 -* message_tokens - 消息中的令牌数 -* answer_tokens - 回答中的令牌数 -* total_tokens - 消息和回答中的总令牌数 -* error - 错误信息 -* inputs - 输入数据 -* outputs - 输出数据 -* file_list - 处理的文件列表 -* start_time - 开始时间 -* end_time - 结束时间 -* message_file_data - 与消息关联的文件数据 -* conversation_mode - 对话模式 -* 元数据 - * conversation_id - 对话 ID - * ls_provider - 模型供应商 - * ls_model_name - 模型 ID - * status - 消息状态 - * from_end_user_id - 发送用户的 ID - * from_account_id - 发送账户的 ID - * agent_based - 消息是否基于代理 - * workflow_run_id - 工作流运行 ID - * from_source - 消息来源 - -#### **审核追踪信息** - -**用于追踪对话审核** - -| 审核 | Weave 追踪 | -| ------------- | ---------------------- | -| user_id | 放置在元数据中 | -| "moderation" | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \[moderation] | tags | -| message_id | parent_run_id | - -**审核追踪信息** - -* message_id - 消息 ID -* user_id: 用户 ID -* workflow_app_log_id - Workflow 应用日志 ID -* inputs - 审核输入数据 -* message_data - 消息数据 -* flagged - 内容是否被标记为需要注意 -* action - 采取的特定操作 -* preset_response - 预设响应 -* start_time - 审核开始时间 -* end_time - 审核结束时间 -* 元数据 - * message_id - 消息 ID - * action - 采取的特定操作 - * preset_response - 预设响应 - -#### **建议问题追踪信息** - -**用于追踪建议的问题** - -| 建议问题 | Weave 追踪 | -| ---------------------- | ---------------------- | -| user_id | 放置在元数据中 | -| suggested_question | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| suggested_question | tags | -| message_id | parent_run_id | - -**消息追踪信息** - -* message_id - 消息 ID -* message_data - 消息数据 -* inputs - 输入内容 -* outputs - 输出内容 -* start_time - 开始时间 -* end_time - 结束时间 -* total_tokens - 令牌数 -* status - 消息状态 -* error - 错误信息 -* from_account_id - 发送账户的 ID -* agent_based - 消息是否基于代理 -* from_source - 消息来源 -* model_provider - 模型供应商 -* model_id - 模型 ID -* suggested_question - 建议的问题 -* level - 状态级别 -* status_message - 状态消息 -* 元数据 - * message_id - 消息 ID - * ls_provider - 模型供应商 - * ls_model_name - 模型 ID - * status - 消息状态 - * from_end_user_id - 发送用户的 ID - * from_account_id - 发送账户的 ID - * workflow_run_id - 工作流运行 ID - * from_source - 消息来源 - -#### **数据集检索追踪信息** - -**用于追踪知识库检索** - -| 数据集检索 | Weave 追踪 | -| --------------------- | --------------------- | -| user_id | 放置在元数据中 | -| dataset_retrieval | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| dataset_retrieval | tags | -| message_id | parent_run_id | - -**数据集检索追踪信息** - -* message_id - 消息 ID -* inputs - 输入内容 -* documents - 文档数据 -* start_time - 开始时间 -* end_time - 结束时间 -* message_data - 消息数据 -* 元数据 - * message_id - 消息 ID - * ls_provider - 模型供应商 - * ls_model_name - 模型 ID - * status - 消息状态 - * from_end_user_id - 发送用户的 ID - * from_account_id - 发送账户的 ID - * agent_based - 消息是否基于代理 - * workflow_run_id - 工作流运行 ID - * from_source - 消息来源 - -#### **工具追踪信息** - -**用于追踪工具调用** - -| 工具 | Weave 追踪 | -| --------------------- | ----------------------- | -| user_id | 放置在元数据中 | -| tool_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| \["tool", tool_name] | tags | -| message_id | parent_run_id | - -#### **工具追踪信息** - -* message_id - 消息 ID -* tool_name - 工具名称 -* start_time - 开始时间 -* end_time - 结束时间 -* tool_inputs - 工具输入 -* tool_outputs - 工具输出 -* message_data - 消息数据 -* error - 错误信息（如果有） -* inputs - 消息的输入 -* outputs - 消息的输出 -* tool_config - 工具配置 -* time_cost - 时间成本 -* tool_parameters - 工具参数 -* file_url - 关联文件的 URL -* 元数据 - * message_id - 消息 ID - * tool_name - 工具名称 - * tool_inputs - 工具输入 - * tool_outputs - 工具输出 - * tool_config - 工具配置 - * time_cost - 时间成本 - * error - 错误信息（如果有） - * tool_parameters - 工具参数 - * message_file_id - 消息文件 ID - * created_by_role - 创建者的角色 - * created_user_id - 创建者的用户 ID - -**生成名称追踪信息** - -**用于追踪对话标题生成** - -| 生成名称 | Weave 追踪 | -| ----------------- | ---------------------- | -| user_id | 放置在元数据中 | -| generate_name | name | -| start_time | start_time | -| end_time | end_time | -| inputs | inputs | -| outputs | outputs | -| metadata | extra | -| generate_name | tags | - -**生成名称追踪信息** - -* conversation_id - 对话 ID -* inputs - 输入数据 -* outputs - 生成的对话名称 -* start_time - 开始时间 -* end_time - 结束时间 -* tenant_id - 租户 ID -* 元数据 - * conversation_id - 对话 ID - * tenant_id - 租户 ID + 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 + + From c32546e6f8e7bd3ecfd3efd64e7e04a8e176167d Mon Sep 17 00:00:00 2001 From: -LAN- Date: Wed, 4 Nov 2026 22:10:11 +0800 Subject: [PATCH 2/2] fix: limit tracing docs to factual corrections Restore the original introductions, screenshots, headings, and reference structure across the seven self-host tracing integration guides. Keep only corrections to provider configuration requirements, exported field mappings, asynchronous delivery, and Agent tracing prerequisites. Apply the same factual changes to the English, Chinese, and Japanese pages based on Dify 0fe1b06d1ea096bde2bba619a4cc1973bea9cdd2. --- .../monitor/integrations/integrate-aliyun.mdx | 411 +++++++++-- .../monitor/integrations/integrate-arize.mdx | 561 +++++++++++++-- .../integrations/integrate-langfuse.mdx | 632 +++++++++++++++-- .../integrations/integrate-langsmith.mdx | 636 ++++++++++++++++-- .../monitor/integrations/integrate-opik.mdx | 581 ++++++++++++++-- .../integrations/integrate-phoenix.mdx | 610 +++++++++++++++-- .../monitor/integrations/integrate-weave.mdx | 359 ++++++++-- .../monitor/integrations/integrate-aliyun.mdx | 413 ++++++++++-- .../monitor/integrations/integrate-arize.mdx | 516 ++++++++++++-- .../integrations/integrate-langfuse.mdx | 632 +++++++++++++++-- .../integrations/integrate-langsmith.mdx | 372 ++++++++-- .../monitor/integrations/integrate-opik.mdx | 536 +++++++++++++-- .../integrations/integrate-phoenix.mdx | 565 ++++++++++++++-- .../monitor/integrations/integrate-weave.mdx | 361 ++++++++-- .../monitor/integrations/integrate-aliyun.mdx | 226 +++++-- .../monitor/integrations/integrate-arize.mdx | 343 ++++++++-- .../integrations/integrate-langfuse.mdx | 632 +++++++++++++++-- .../integrations/integrate-langsmith.mdx | 400 +++++++++-- .../monitor/integrations/integrate-opik.mdx | 361 ++++++++-- .../integrations/integrate-phoenix.mdx | 394 +++++++++-- .../monitor/integrations/integrate-weave.mdx | 362 ++++++++-- 21 files changed, 8990 insertions(+), 913 deletions(-) diff --git a/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index 7a5d4b86b..ecf939bbe 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -4,77 +4,396 @@ sidebarTitle: Alibaba Cloud Monitor description: Send traces from Dify applications to Alibaba Cloud Monitor (ARMS) via OpenTelemetry --- -## Connect Your App +## What is Alibaba Cloud Monitor -Ask your deployment administrator for the License Key and HTTP trace URL, using [Alibaba Cloud's connection instructions](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin). They should choose the region and network address that your Dify services can reach. +Alibaba Cloud provides a fully managed, maintenance-free observability platform that enables one-click monitoring, tracing, and evaluation of Dify applications. -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Cloud Monitor**, click **Config** and enter the connection details: + + Alibaba Cloud Monitor natively supports Python/Golang/Java applications through [LoongSuite](https://github.com/alibaba/loongsuite-python-agent) agents and open-source OpenTelemetry agents. In addition to one-click monitoring of Dify LLM applications, it also supports end-to-end observability of Dify components and their upstream and downstream dependencies through non-invasive agents. + + For more details, please refer to the [Cloud Monitor documentation](https://www.alibabacloud.com/help/en/cms/cloudmonitor-1-0/product-overview/what-is-cloudmonitor?spm=a3c0i.63551.2277339270.1.76c7112eeKEvSr). + -| Field | Required | Value | -|:------|:---------|:------| -| **License Key** | Yes | The collector's authentication key, entered separately from the endpoint. | -| **Endpoint** | Yes | The collector's HTTP(S) base URL. An explicit port is allowed. | -| **App Name** | Yes | A name you choose for the application in the ARMS console. | +## How to Configure Alibaba Cloud Monitor -From the HTTP trace URL, enter the part before `/adapt_` in **Endpoint** and the authentication token in **License Key**. For this example URL: +### 1. Get Alibaba Cloud Endpoint and License Key -```text -https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces -``` +1. Log in to the [ARMS console](https://account.alibabacloud.com/login/login.htm?spm=5176.12901015-2.0.0.68d74b84XRatpU), and click **Integration Center** in the left navigation bar. +2. In the **Server-side Applications** area, click the **OpenTelemetry** card. +3. In the **OpenTelemetry** panel that appears, select **HTTP** as the export protocol, and select the connection method and region according to your actual deployment. -- **Endpoint**: `https://tracing-analysis-dc-hz.aliyuncs.com` -- **License Key**: `example-key` + + ![Get Alibaba Cloud Access Point](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/get_endpoint.png) + -Keep any port for the HTTP endpoint; a gRPC port such as `8090` won't work here. +4. Save the **Public Endpoint** and **Authentication Token (License Key)**. -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Cloud Monitor replaces the current selection. + + Use the HTTP(S) base URL as **Endpoint**, keeping the port if the HTTP collector requires one. Enter the token separately as **License Key**. Do not include `adapt_` or the ingestion path, and do not use the gRPC port `8090`; Dify constructs the OTLP/HTTP ingestion URL. + -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. +### 2. Configure Cloud Monitor in Dify -## What Dify Sends + + Requires Dify v1.6.0 or later. + -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +1. Log in to the Dify console and navigate to the application you want to monitor. +2. Open **Monitoring** in the left navigation bar. +3. Click **Tracing app performance**, then click **Configure** in the **Cloud Monitor** area. -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. + + ![Configure Alibaba Cloud Monitor](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/config_cms.png) + -In Alibaba Cloud Monitor, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill the platform's built-in cost fields. +4. In the dialog that appears, enter the **License Key** and **Endpoint** obtained in step 1, and customize the **App Name** (the application name displayed in the ARMS console), then click **Save & Enable**. -### Include Agent Calls and Content +## View Monitoring Data in Alibaba Cloud Monitor - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +After configuration, debug or production data from applications in Dify can be monitored in Cloud Monitor. + +### Method 1: Jump to ARMS Console from Dify Application + +In the Dify console, select an application with tracing enabled, go to **Tracing Configuration**, and click **View** in the **Cloud Monitor** area. -Under **Agent data capture** in the app's tracing settings: +### Method 2: View Directly in ARMS Console -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. +Go to the corresponding Dify application in the **LLM Application Monitoring > Application List** page of the ARMS console. + +## Access More Data + +Cloud Monitor provides multi-language non-invasive agents that support accessing various components of the Dify cluster to achieve end-to-end tracing. + +| Dify Component | Agent | Details | +|----------------|-------|---------| +| Nginx | OpenTelemetry Agent | [Use OpenTelemetry for Nginx Tracing](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx?spm=a2c63.l28256.help-menu-search-90275.d_1) | +| API | LoongSuite-Python Agent | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | +| Sandbox | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | +| Worker | OpenTelemetry Agent | [Submit Python Application Data via OpenTelemetry](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications?spm=a2c63.p38356.help-menu-90275.d_2_0_5_0.18ee53a4EGoGuS) | +| Plugin-Daemon | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +## Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +Cloud Monitor supports collecting data from Dify's Workflow/Chatflow/Chat/Agent applications, including execution details of workflows and workflow nodes, covering model calls, tool calls, knowledge retrieval, execution details of various process nodes, as well as metadata such as conversations and user information. + +### Workflow/Chatflow Trace Information + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowAlibaba Cloud Monitor Trace
workflow\_idUnique identifier of the Workflow
conversation\_idConversation ID
workflow\_run\_idID of this run
tenant\_idTenant ID
elapsed\_timeDuration of this run
statusRun status
versionWorkflow version
total\_tokensTotal tokens used in this run
file\_listList of processed files
triggered\_fromSource that triggered this run
workflow\_run\_inputsInput data for this run
workflow\_run\_outputsOutput data for this run
errorErrors that occurred during this run
queryQuery used during runtime
workflow\_app\_log\_idWorkflow application log ID
message\_idAssociated message ID
start\_timeRun start time
end\_timeRun end time
+ +**Workflow Trace Metadata** + +* workflow\_id - Unique identifier of the Workflow +* conversation\_id - Conversation ID +* workflow\_run\_id - ID of this run +* tenant\_id - Tenant ID +* elapsed\_time - Duration of this run +* status - Run status +* version - Workflow version +* total\_tokens - Total tokens used in this run +* file\_list - List of processed files +* triggered\_from - Trigger source + +### Message Trace Information + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MessageAlibaba Cloud Monitor Trace
message\_idMessage ID
message\_dataMessage data
end\_user\_session\_idUser's session\_id
conversation\_modelConversation model
message\_tokensNumber of tokens in the message
answer\_tokensNumber of tokens in the answer
total\_tokensTotal tokens in message and answer
errorError information
inputsInput data
outputsOutput data
file\_listList of processed files
start\_timeStart time
end\_timeEnd time
conversation\_modeConversation mode
+ +**Message Trace Metadata** + +* conversation\_id - ID of the conversation to which the message belongs +* ls\_provider - Model provider +* ls\_model\_name - Model ID +* status - Message status +* from\_end\_user\_id - ID of the sending user +* from\_account\_id - ID of the sending account +* agent\_based - Whether it is agent-based +* workflow\_run\_id - Workflow run ID +* from\_source - Message source +* message\_id - Message ID + +### Dataset Retrieval Trace Information -## Verify a New Trace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalAlibaba Cloud Monitor Trace
message\_idMessage ID
inputsInput content
documentsDocument data
start\_timeStart time
end\_timeEnd time
message\_dataMessage data
-1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Cloud Monitor** to open the ARMS LLM console. -3. Find the application name you entered, then locate the new trace by its run time and inspect its child spans. +**Dataset Retrieval Trace Metadata** -Traces may take time to appear after the run finishes. +* message\_id - Message ID +* ls\_provider - Model provider +* ls\_model\_name - Model ID +* status - Message status +* from\_end\_user\_id - ID of the sending user +* from\_account\_id - ID of the sending account +* agent\_based - Whether it is agent-based +* workflow\_run\_id - Workflow run ID +* from\_source - Message source -## Troubleshooting +### Tool Trace Information - - - Saving tests collector access without creating a real trace. Confirm that Cloud Monitor is selected and tracing is enabled. In Alibaba Cloud Monitor, open the application name you configured. Then run the app again. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolAlibaba Cloud Monitor Trace
message\_idMessage ID
tool\_nameTool name
start\_timeStart time
end\_timeEnd time
tool\_inputsTool inputs
tool\_outputsTool outputs
message\_dataMessage data
errorError information (if any)
inputsInput content of the message
outputsAnswer content of the message
tool\_configTool configuration
time\_costTime cost
tool\_parametersTool parameters
file\_urlURL of associated file
- Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. +**Tool Trace Metadata** - For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - +* message\_id - Message ID +* tool\_name - Tool name +* tool\_inputs - Tool inputs +* tool\_outputs - Tool outputs +* tool\_config - Tool configuration +* time\_cost - Time cost +* error - Error information +* tool\_parameters - Tool parameters +* message\_file\_id - Message file ID +* created\_by\_role - Creator role +* created\_user\_id - Creator user ID diff --git a/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx index 2d605379d..018e5001f 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,72 +1,549 @@ --- title: Integrate with Arize sidebarTitle: Arize -description: Connect a Dify app to Arize, verify new traces, and choose which Agent data to send --- -## Connect Your App -In Arize, get the API key and current Space ID from **Settings** > **API Keys**; see the [Arize quickstart](https://arize.com/docs/ax/quickstarts) for details. Choose a destination project name. To connect Phoenix instead, use the [Phoenix integration](/en/self-host/use-dify/monitor/integrations/integrate-phoenix). +### What is Arize -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Arize**, click **Config** and enter the connection details: +[Arize AX](https://arize.com/products/ax/) is [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host)'s full-featured platform for observability, online and offline evaluation, monitoring, and experimentation in LLM and agent-driven applications. Built for production teams, AI-native companies, and enterprises, it runs as a managed cloud service or an enterprise self-hosted deployment. -| Field | Required | Value | -|:------|:---------|:------| -| **API Key** | Yes | An Arize API key with ingestion access. | -| **Space ID** | Yes | The Arize space receiving the traces. | -| **Project** | Yes | The destination project name. | -| **Endpoint** | No | Defaults to `https://otlp.arize.com`. For a custom collector, use the address your administrator provides. | +If you'd rather run an open-source stack for local development, experimentation, or single-container self-hosting, set up the [Phoenix integration](/en/self-host/use-dify/monitor/integrations/integrate-phoenix) instead. -A custom **Endpoint** must accept OTLP/gRPC. Ask your administrator for its hostname and port, without an HTTP path such as `/v1/traces`. +Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality. -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Arize replaces the current selection. +### How to Configure Arize -Saved credentials are hidden when you edit. Leave **API Key** and **Space ID** blank to keep their saved values while **Endpoint** is unchanged. Re-enter both if you change the endpoint. +#### 1. Register/Login to [Arize](https://app.arize.com/auth/join) -## What Dify Sends +#### 2. Get your Arize API Key -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +Retrieve your Arize API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. + + ![Arize API Key](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) + -In Arize, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill Arize's built-in cost fields. +#### 3. Integrate Arize with Dify -### Include Agent Calls and Content +Configure Arize in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - + + ![Tracing App Performance](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) + + +After clicking configure, paste the **API Key**, **Space ID** and **project name** into the configuration and save. **Endpoint** defaults to `https://otlp.arize.com` and must identify an OTLP/gRPC collector. URL paths are not used; do not enter an HTTP `/v1/traces` endpoint. + + + ![Configure Arize](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) + -Under **Agent data capture** in the app's tracing settings: +Once successfully saved, you can view the monitoring status on the current page. -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. + + ![Configure Arize](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) + -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### **Workflow/Chatflow Trace Information** + +**Used to track workflows and chatflows** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowArize Trace
workflow_run_idspan_id
user_idmetadata.user_id
workflowname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
Model token consumption (LLM calls)llm.token_count.prompt / completion / total
metadatametadata
errorstatus.code / status.message
Session IDsession.id
+**Workflow Trace Info** + +- workflow_id - Unique identifier of the workflow +- conversation_id - Conversation ID +- workflow_run_id - ID of the current run +- tenant_id - Tenant ID +- elapsed_time - Time taken for the current run +- status - Run status +- version - Workflow version +- total_tokens - Total tokens used in the current run +- file_list - List of processed files +- triggered_from - Source that triggered the current run +- workflow_run_inputs - Input data for the current run +- workflow_run_outputs - Output data for the current run +- error - Errors encountered during the current run +- query - Query used during the run +- workflow_app_log_id - Workflow application log ID +- message_id - Associated message ID +- start_time - Start time of the run +- end_time - End time of the run +- workflow node executions - Information about workflow node executions +- Metadata + - workflow_id - Unique identifier of the workflow + - conversation_id - Conversation ID + - workflow_run_id - ID of the current run + - tenant_id - Tenant ID + - elapsed_time - Time taken for the current run + - status - Run status + - version - Workflow version + - total_tokens - Total tokens used in the current run + - file_list - List of processed files + - triggered_from - Source that triggered the current run + +#### **Message Trace Information** + +**Used to track LLM-related conversations** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChatArize Trace
message_idspan_id
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
Model token consumption (LLM calls)llm.token_count.prompt / completion / total
metadatametadata
Session IDsession.id
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- end_user_session_id - User session ID +- conversation_model - Conversation mode +- message_tokens - Number of tokens in the message +- answer_tokens - Number of tokens in the answer +- total_tokens - Total number of tokens in the message and answer +- error - Error information +- inputs - Input data +- outputs - Output data +- file_list - List of processed files +- start_time - Start time +- end_time - End time +- conversation_mode - Conversation mode +- Metadata + - conversation_id - Conversation ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Moderation Trace Information** + +**Used to track conversation moderation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationArize Tool
user_idmetadata.user_id
moderationname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
action, flaggedoutput.value
metadatametadata
+**Moderation Trace Info** + +- message_id - Message ID +- user_id: User ID +- workflow_app_log_id - Workflow application log ID +- inputs - Moderation input data +- message_data - Message data +- flagged - Whether the content is flagged for attention +- action - Specific actions taken +- preset_response - Preset response +- start_time - Moderation start time +- end_time - Moderation end time +- Metadata + - message_id - Message ID + - action - Specific actions taken + - preset_response - Preset response + +#### **Suggested Question Trace Information** + +**Used to track suggested questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionArize Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
suggested_questionoutput.value
metadatametadata
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- inputs - Input content +- outputs - Output content +- start_time - Start time +- end_time - End time +- total_tokens - Number of tokens +- status - Message status +- error - Error information +- from_account_id - ID of the sending account +- agent_based - Whether the message is agent-based +- from_source - Message source +- model_provider - Model provider +- model_id - Model ID +- suggested_question - Suggested question +- level - Status level +- status_message - Status message +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Dataset Retrieval Trace Information** + +**Used to track knowledge base retrieval** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalArize Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
documentsoutput.value
metadatametadata
message_idparent_span_id
+**Dataset Retrieval Trace Info** + +- message_id - Message ID +- inputs - Input content +- documents - Document data +- start_time - Start time +- end_time - End time +- message_data - Message data +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Tool Trace Information** -## Verify a New Trace +**Used to track tool invocation** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Arize**. If the shortcut is unavailable, open your Arize space and project directly. -3. Find the new trace by its run time and open it to inspect its child spans. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolArize Tool
user_idmetadata.user_id
tool_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
tool_inputsinput.value
tool_outputsoutput.value
metadatametadata
+#### **Tool Trace Info** -Traces may take time to appear after the run finishes. +- message_id - Message ID +- tool_name - Tool name +- start_time - Start time +- end_time - End time +- tool_inputs - Tool inputs +- tool_outputs - Tool outputs +- message_data - Message data +- error - Error information, if any +- inputs - Inputs for the message +- outputs - Outputs of the message +- tool_config - Tool configuration +- time_cost - Time cost +- tool_parameters - Tool parameters +- file_url - URL of the associated file +- Metadata + - message_id - Message ID + - tool_name - Tool name + - tool_inputs - Tool inputs + - tool_outputs - Tool outputs + - tool_config - Tool configuration + - time_cost - Time cost + - error - Error information, if any + - tool_parameters - Tool parameters + - message_file_id - Message file ID + - created_by_role - Role of the creator + - created_user_id - User ID of the creator -## Troubleshooting +**Generate Name Trace Information** - - - Saving tests collector access without creating a real trace. Confirm that Arize is selected and tracing is enabled. In Arize, open the configured space and project. Then run the app again. +**Used to track conversation title generation** - Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The gRPC collector must be reachable from Dify's API and workers. Ask your administrator to check its hostname, port, and network access. Use a reachable server address: loopback addresses such as `localhost` aren't accepted. - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NameArize Tool
user_idmetadata.user_id
generate_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
metadatametadata
+**Generate Name Trace Info** -For help evaluating the traces you collect, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/). +- conversation_id - Conversation ID +- inputs - Input data +- outputs - Generated conversation name +- start_time - Start time +- end_time - End time +- tenant_id - Tenant ID +- Metadata + - conversation_id - Conversation ID + - tenant_id - Tenant ID diff --git a/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index f05ecd3c5..b54eaf5e1 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,75 +1,619 @@ --- title: Integrate with Langfuse sidebarTitle: Langfuse -description: Connect a Dify app to Langfuse, verify new traces, and choose which Agent data to send --- -## Connect Your App +### What is Langfuse -Create a Langfuse project and get its [API keys](https://langfuse.com/faq/all/where-are-langfuse-api-keys) from **Project Settings** > **API Keys**. For Langfuse Cloud, choose the [base URL for your region](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url) without the `/api/public` suffix. For a self-hosted instance, ask its administrator for the base URL. +Langfuse is an open-source LLM engineering platform that helps teams collaborate on debugging, analyzing, and iterating their applications. -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Langfuse**, click **Config** and enter the connection details: + + Introduction to Langfuse: [https://langfuse.com/](https://langfuse.com/) + -| Field | Required | Value | -|:------|:---------|:------| -| **Secret Key** | Yes | The project's secret key. | -| **Public Key** | Yes | The matching public key. | -| **Host** | Yes | Your Langfuse instance's HTTP(S) base URL. | +### How to Configure Langfuse - -This integration requires Langfuse's legacy ingestion API, `/api/public/ingestion`, to receive trace data. Langfuse v4 deployments using `events_only` mode don't accept these traces. Check [Langfuse's ingestion compatibility](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api) with your Langfuse administrator before connecting. - +1. Register and log in to Langfuse on the [official website](https://langfuse.com/) +2. Create a project in Langfuse. After logging in, click **New** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring. -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Langfuse replaces the current selection. + + ![Create a Project in Langfuse](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) + -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Host** is unchanged. Re-enter them if you change the destination. +Edit a name for the project. -## What Dify Sends + + ![Create a Project in Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) + -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +3. Create project API credentials. In the left sidebar of the project, click **Settings** to open the settings. -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. + + ![Create Project API Credentials](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) + -In Langfuse, open a generation to inspect a model call's captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. +In Settings, click **Create API Keys** to create project API credentials. -### Include Agent Calls and Content + + ![Create Project API Credentials](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) + - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +Copy and save the **Secret Key**, **Public Key**, and **Host**. + + + ![Get API Key Configuration](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) + + +4. Configure Langfuse in Dify. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + ![Configure Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) + + +After clicking configure, paste the **Secret Key, Public Key, Host** created in Langfuse into the configuration and save. **Host** must be the base URL for your project's region or self-hosted instance, without `/api/public`. This integration requires the [legacy ingestion API](https://langfuse.com/docs/api-and-data-platform/features/public-api); an `events_only` instance does not accept these traces. + + + ![Configure Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) + + +Once successfully saved, you can view the status on the current page. + + + ![View Configuration Status](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) + -Under **Agent data capture** in the app's tracing settings: +### View Monitoring Data in Langfuse -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. +After configuration, debugging or production data of the application in Dify can be viewed in Langfuse. + + + ![Configuration, Debugging or Production Data of the Application in Dify Can Be](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) + + + + ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) + -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### List of monitoring data + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### Trace the information of Workflow and Chatflow + +**Tracing Workflow and Chatflow** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowLangFuse Trace
workflow_run_idid
user_iduserId
workflowname
start\_timetimestamp / startTime
end\_timeendTime (observations)
inputsinput
outputsoutput
Model token consumption (LLM calls)usage
metadatametadata
errorlevel (observations)
errorstatusMessage (observations)
Session IDsessionId
Parent span (when present)parentObservationId (nested observations)
+**Workflow Trace Info** + +* workflow\_id - Unique ID of Workflow +* conversation\_id - Conversation ID +* workflow\_run\_id - Workflow ID of this runtime +* tenant\_id - Tenant ID +* elapsed\_time - Elapsed time at this runtime +* status - Runtime status +* version - Workflow version +* total\_tokens - Total token used at this runtime +* file\_list - List of files processed +* triggered\_from - Source that triggered this runtime +* workflow\_run\_inputs - Input of this workflow +* workflow\_run\_outputs - Output of this workflow +* error - Error Message +* query - Queries used at runtime +* workflow\_app\_log\_id - Workflow Application Log ID +* message\_id - Relevant Message ID +* start\_time - Start time of this runtime +* end\_time - End time of this runtime +* workflow node executions - Workflow node runtime information +* Metadata + * workflow\_id - Unique ID of Workflow + * conversation\_id - Conversation ID + * workflow\_run\_id - Workflow ID of this runtime + * tenant\_id - Tenant ID + * elapsed\_time - Elapsed time at this runtime + * status - Operational state + * version - Workflow version + * total\_tokens - Total token used at this runtime + * file\_list - List of files processed + * triggered\_from - Source that triggered this runtime + +#### Message Trace Info + +**For trace llm conversation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MessageLangFuse Generation/Trace
message\_idid
end\_user\_session\_iduserId
messagename
start\_timetimestamp / startTime
end\_timeendTime (observations)
inputsinput
outputsoutput
Model token consumption (LLM calls)usage
metadatametadata
errorlevel (observations)
errorstatusMessage (observations)
Session IDsessionId
+**Message Trace Info** + +* message\_id - Message ID +* message\_data - Message data +* end\_user\_session\_id - Session ID for user +* conversation\_model - Conversation model +* message\_tokens - Message tokens +* answer\_tokens - Answer Tokens +* total\_tokens - Total Tokens from Message and Answer +* error - Error Message +* inputs - Input data +* outputs - Output data +* file\_list - List of files processed +* start\_time - Start time +* end\_time - End time +* conversation\_mode - Conversation mode +* Metadata + * conversation\_id - Conversation ID + * ls\_provider - Model provider + * ls\_model\_name - Model ID + * status - Message status + * from\_end\_user\_id - Sending user's ID + * from\_account\_id - Sending account's ID + * agent\_based - Whether agent based + * workflow\_run\_id - Workflow ID of this runtime + * from\_source - Message source + * message\_id - Message ID + +#### Moderation Trace Information + +**Used to track conversation moderation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationLangFuse Generation/Trace
user\_idmetadata.user_id
moderationname
start\_timestartTime
end\_timeendTime (observations)
inputsinput
action, flaggedoutput
metadatametadata
message\_idtraceId
+**Message Trace Info** + +* message\_id - Message ID +* user\_id - user ID +* workflow\_app\_log\_id workflow\_app\_log\_id +* inputs - Input data for review +* message\_data - Message Data +* flagged - Whether it is flagged for attention +* action - Specific actions to implement +* preset\_response - Preset response +* start\_time - Start time of review +* end\_time - End time of review +* Metadata + * message\_id - Message ID + * action - Specific actions to implement + * preset\_response - Preset response + +#### Suggested Question Trace Information + +**Used to track suggested questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionLangFuse Generation/Trace
user\_idmetadata.user_id
suggested\_questionname
start\_timestartTime
end\_timeendTime (observations)
inputsinput
suggested_questionoutput
metadatametadata
message\_idtraceId
+**Message Trace Info** + +* message\_id - Message ID +* message\_data - Message data +* inputs - Input data +* outputs - Output data +* start\_time - Start time +* end\_time - End time +* total\_tokens - Total tokens +* status - Message Status +* error - Error Message +* from\_account\_id - Sending account ID +* agent\_based - Whether agent based +* from\_source - Message source +* model\_provider - Model provider +* model\_id - Model ID +* suggested\_question - Suggested question +* level - Status level +* status\_message - Message status +* Metadata + * message\_id - Message ID + * ls\_provider - Model Provider + * ls\_model\_name - Model ID + * status - Message status + * from\_end\_user\_id - Sending user's ID + * from\_account\_id - Sending Account ID + * workflow\_run\_id - Workflow ID of this runtime + * from\_source - Message source + +#### Dataset Retrieval Trace Information + +**Used to track knowledge base retrieval** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalLangFuse Generation/Trace
user\_idmetadata.user_id
dataset\_retrievalname
start\_timestartTime
end\_timeendTime (observations)
inputsinput
documentsoutput
metadatametadata
message\_idtraceId
+**Dataset Retrieval Trace Info** + +* message\_id - Message ID +* inputs - Input Message +* documents - Document data +* start\_time - Start time +* end\_time - End time +* message\_data - Message data +* Metadata + * message\_id - Message ID + * ls\_provider - Model Provider + * ls\_model\_name - Model ID + * status - Model status + * from\_end\_user\_id - Sending user's ID + * from\_account\_id - Sending account's ID + * agent\_based - Whether agent based + * workflow\_run\_id - Workflow ID of this runtime + * from\_source - Message Source + +#### Tool Trace Information + +**Used to track tool invocation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolLangFuse Generation/Trace
user\_idmetadata.user_id
tool\_namename
start\_timestartTime
end\_timeendTime (observations)
tool_inputsinput
tool_outputsoutput
metadatametadata
message\_idtraceId
+**Tool Trace Info** + +* message\_id - Message ID +* tool\_name - Tool Name +* start\_time - Start time +* end\_time - End time +* tool\_inputs - Tool inputs +* tool\_outputs - Tool outputs +* message\_data - Message data +* error - Error Message, if exist +* inputs - Input of Message +* outputs - Output of Message +* tool\_config - Tool config +* time\_cost - Time cost +* tool\_parameters - Tool Parameters +* file\_url - URL of relevant files +* Metadata + * message\_id - Message ID + * tool\_name - Tool Name + * tool\_inputs - Tool inputs + * tool\_outputs - Tool outputs + * tool\_config - Tool config + * time\_cost - Time. cost + * error - Error Message + * tool\_parameters - Tool parameters + * message\_file\_id - Message file ID + * created\_by\_role - Created by role + * created\_user\_id - Created user ID + +#### Generate Name Trace -## Verify a New Trace +**Used to track conversation title generation** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Langfuse** to open the configured project. -3. Find the new trace by its run time. Open it to inspect the model generations or node spans. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NameLangFuse Generation/Trace
user\_idmetadata.user_id
generate\_namename
start\_timestartTime
end\_timeendTime (observations)
inputsinput
outputsoutput
metadatametadata
+**Generate Name Trace Info** -Traces may take time to appear after the run finishes. +* conversation\_id - Conversation ID +* inputs - Input data +* outputs - Generated session name +* start\_time - Start time +* end\_time - End time +* tenant\_id - Tenant ID +* Metadata + * conversation\_id - Conversation ID + * tenant\_id - Tenant ID -## Troubleshooting - - - Saving the configuration checks project access. Confirm that Langfuse is selected and tracing is enabled. Then run the app again and check the same project. +### Langfuse Prompt Management - Ask your administrator to check worker logs for ingestion errors and confirm that Langfuse accepts data through `/api/public/ingestion`. They should also check the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. +The [Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) (community maintained) lets you use prompts that are [managed and versioned in Langfuse](https://langfuse.com/docs/prompt-management/get-started) in your Dify applications, enhancing your LLM application development workflow. Key features include: - For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - +- **Get Prompt**: Fetch specific prompts managed in Langfuse. +- **Search Prompts**: Search for prompts in Langfuse using various filters. +- **Update Prompt**: Create new versions of prompts in Langfuse and set tags/labels. -To use prompts managed in Langfuse, see the community-maintained [Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) for installation and usage. +This integration streamlines the process of managing and versioning your prompts, contributing to more efficient development and iteration cycles. You can find the plugin and installation instructions [here](https://github.com/gao-ai-com/dify-plugin-langfuse). diff --git a/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index 5db1b7eb9..3c35b95f2 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,71 +1,625 @@ --- title: Integrate with LangSmith sidebarTitle: LangSmith -description: Connect a Dify app to LangSmith, verify new traces, and choose which Agent data to send --- -## Connect Your App -Get a [LangSmith API key](https://docs.langchain.com/langsmith/create-account-api-key) with access to read projects and send traces in the target workspace. Choose the exact project name you want to use. +### What is LangSmith -In the Dify app, open **Monitoring** > **Tracing app performance**. For **LangSmith**, click **Config** and enter the connection details: +LangSmith is a platform for building production-grade LLM applications. It is used for developing, collaborating, testing, deploying, and monitoring LLM applications. -| Field | Required | Value | -|:------|:---------|:------| -| **API Key** | Yes | A key with project read and trace write access. | -| **Project** | Yes | The project name. LangSmith creates it on the first trace if it doesn't exist. | -| **Endpoint** | No | Defaults to `https://api.smith.langchain.com`. A custom API endpoint must use HTTPS; keep any required path prefix. | + +For more details, please refer to [LangSmith](https://www.langchain.com/langsmith). + -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting LangSmith replaces the current selection. +### How to Configure LangSmith -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. +#### 1. Register/Login to [LangSmith](https://www.langchain.com/langsmith) -## What Dify Sends +#### 2. Create a Project -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +Create a project in LangSmith. After logging in, click **New Project** on the homepage to create your own project. The **project** will be used to associate with **applications** in Dify for data monitoring. -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. + + ![Create a Project in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) + -In LangSmith, open a model run to inspect its captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. +Once created, you can view all created projects in the Projects section. -### Include Agent Calls and Content + + ![View Created Projects in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) + - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +#### 3. Create Project Credentials + +Find the project settings **Settings** in the left sidebar. + + + ![Project Settings](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) + + +Click **Create API Key** to create project credentials. + + + ![Create a Project API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) + + +Select **Personal Access Token** for subsequent API authentication. + + + ![Create an API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) + + +Copy and save the created API key. + + + ![Copy API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) + + +#### 4. Integrate LangSmith with Dify + +Configure LangSmith in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + ![Tracing App Performance](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/b6c7e5d4c2ca2092d59465cca27bc69c.png) + + +After clicking configure, paste the **API Key** and **project name** into the configuration and save. The key must allow project reads and trace writes. **Endpoint** defaults to `https://api.smith.langchain.com`; a custom API endpoint must use HTTPS. + + + ![Configure LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/93dfabcadb7b2ff597f54beb5e642124.png) + + + +The configured project name needs to match the project set in LangSmith. If the project does not exist, LangSmith creates it when the first trace arrives, not when the configuration is saved. + + +Once successfully saved, you can view the monitoring status on the current page. + + + ![View Configuration Status](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/43369dc4de8f606c166fae2efab97d73.png) + + +### View Monitoring Data in LangSmith + +Once configured, the debug or production data from applications within Dify can be monitored in LangSmith. + + + ![Debugging Applications in Dify](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a1370fdbb79257cba31a565ac6764802.png) + + +When you switch to LangSmith, you can view detailed operation logs of Dify applications in the dashboard. + + + ![Viewing Application Data in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) + -Under **Agent data capture** in the app's tracing settings: +Detailed LLM operation logs through LangSmith will help you optimize the performance of your Dify application. -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. + + ![Viewing Application Data in LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/beeb4ee50c80de8db7400c1f65727c8c.png) + -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### **Workflow/Chatflow Trace Information** + +**Used to track workflows and chatflows** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowLangSmith Chain
workflow_run_idid
user_idextra.metadata.user_id
workflowname
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
Model token consumption (LLM calls)outputs.usage_metadata
metadataextra.metadata
errorerror
Session IDextra.metadata.session_id
Parent span (when present)parent\_run\_id
+**Workflow Trace Info** + +* workflow\_id - Unique identifier of the workflow +* conversation\_id - Conversation ID +* workflow\_run\_id - ID of the current run +* tenant\_id - Tenant ID +* elapsed\_time - Time taken for the current run +* status - Run status +* version - Workflow version +* total\_tokens - Total tokens used in the current run +* file\_list - List of processed files +* triggered\_from - Source that triggered the current run +* workflow\_run\_inputs - Input data for the current run +* workflow\_run\_outputs - Output data for the current run +* error - Errors encountered during the current run +* query - Query used during the run +* workflow\_app\_log\_id - Workflow application log ID +* message\_id - Associated message ID +* start\_time - Start time of the run +* end\_time - End time of the run +* workflow node executions - Information about workflow node executions +* Metadata + * workflow\_id - Unique identifier of the workflow + * conversation\_id - Conversation ID + * workflow\_run\_id - ID of the current run + * tenant\_id - Tenant ID + * elapsed\_time - Time taken for the current run + * status - Run status + * version - Workflow version + * total\_tokens - Total tokens used in the current run + * file\_list - List of processed files + * triggered\_from - Source that triggered the current run + +#### **Message Trace Information** + +**Used to track LLM-related conversations** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChatLangSmith Chain / LLM
message\_idid
end\_user\_session\_idextra.metadata.end_user_session_id
messagename
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
Model token consumption (LLM calls)outputs.usage_metadata
metadataextra.metadata
errorerror
Session IDextra.metadata.session_id
+**Message Trace Info** + +* message\_id - Message ID +* message\_data - Message data +* end\_user\_session\_id - User session ID +* conversation\_model - Conversation mode +* message\_tokens - Number of tokens in the message +* answer\_tokens - Number of tokens in the answer +* total\_tokens - Total number of tokens in the message and answer +* error - Error information +* inputs - Input data +* outputs - Output data +* file\_list - List of processed files +* start\_time - Start time +* end\_time - End time +* conversation\_mode - Conversation mode +* Metadata + * conversation\_id - Conversation ID + * ls\_provider - Model provider + * ls\_model\_name - Model ID + * status - Message status + * from\_end\_user\_id - ID of the sending user + * from\_account\_id - ID of the sending account + * agent\_based - Whether the message is agent-based + * workflow\_run\_id - Workflow run ID + * from\_source - Message source + +#### **Moderation Trace Information** + +**Used to track conversation moderation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationLangSmith Tool
user\_idextra.metadata.user_id
moderationname
start\_timestart\_time
end\_timeend\_time
inputsinputs
action, flaggedoutputs
metadataextra.metadata
message\_idparent\_run\_id
+**Moderation Trace Info** + +* message\_id - Message ID +* user\_id: User ID +* workflow\_app\_log\_id - Workflow application log ID +* inputs - Moderation input data +* message\_data - Message data +* flagged - Whether the content is flagged for attention +* action - Specific actions taken +* preset\_response - Preset response +* start\_time - Moderation start time +* end\_time - Moderation end time +* Metadata + * message\_id - Message ID + * action - Specific actions taken + * preset\_response - Preset response + +#### **Suggested Question Trace Information** + +**Used to track suggested questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionLangSmith Tool
user\_idextra.metadata.user_id
suggested\_questionname
start\_timestart\_time
end\_timeend\_time
inputsinputs
suggested_questionoutputs
metadataextra.metadata
message\_idparent\_run\_id
+**Message Trace Info** + +* message\_id - Message ID +* message\_data - Message data +* inputs - Input content +* outputs - Output content +* start\_time - Start time +* end\_time - End time +* total\_tokens - Number of tokens +* status - Message status +* error - Error information +* from\_account\_id - ID of the sending account +* agent\_based - Whether the message is agent-based +* from\_source - Message source +* model\_provider - Model provider +* model\_id - Model ID +* suggested\_question - Suggested question +* level - Status level +* status\_message - Status message +* Metadata + * message\_id - Message ID + * ls\_provider - Model provider + * ls\_model\_name - Model ID + * status - Message status + * from\_end\_user\_id - ID of the sending user + * from\_account\_id - ID of the sending account + * workflow\_run\_id - Workflow run ID + * from\_source - Message source + +#### **Dataset Retrieval Trace Information** + +**Used to track knowledge base retrieval** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalLangSmith Retriever
user\_idextra.metadata.user_id
dataset\_retrievalname
start\_timestart\_time
end\_timeend\_time
inputsinputs
documentsoutputs
metadataextra.metadata
message\_idparent\_run\_id
+**Dataset Retrieval Trace Info** + +* message\_id - Message ID +* inputs - Input content +* documents - Document data +* start\_time - Start time +* end\_time - End time +* message\_data - Message data +* Metadata + * message\_id - Message ID + * ls\_provider - Model provider + * ls\_model\_name - Model ID + * status - Message status + * from\_end\_user\_id - ID of the sending user + * from\_account\_id - ID of the sending account + * agent\_based - Whether the message is agent-based + * workflow\_run\_id - Workflow run ID + * from\_source - Message source -## Verify a New Trace +#### **Tool Trace Information** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **LangSmith**. -3. In the configured project, find the new run by its run time and inspect its child runs. +**Used to track tool invocation** -Traces may take time to appear after the run finishes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolLangSmith Tool
user\_idextra.metadata.user_id
tool\_namename
start\_timestart\_time
end\_timeend\_time
tool_inputsinputs
tool_outputsoutputs
metadataextra.metadata
message\_idparent\_run\_id
+#### **Tool Trace Info** -If **View** opens the project list after the first trace arrives, save the configuration again to update the project link. +* message\_id - Message ID +* tool\_name - Tool name +* start\_time - Start time +* end\_time - End time +* tool\_inputs - Tool inputs +* tool\_outputs - Tool outputs +* message\_data - Message data +* error - Error information, if any +* inputs - Inputs for the message +* outputs - Outputs of the message +* tool\_config - Tool configuration +* time\_cost - Time cost +* tool\_parameters - Tool parameters +* file\_url - URL of the associated file +* Metadata + * message\_id - Message ID + * tool\_name - Tool name + * tool\_inputs - Tool inputs + * tool\_outputs - Tool outputs + * tool\_config - Tool configuration + * time\_cost - Time cost + * error - Error information, if any + * tool\_parameters - Tool parameters + * message\_file\_id - Message file ID + * created\_by\_role - Role of the creator + * created\_user\_id - User ID of the creator -## Troubleshooting +**Generate Name Trace Information** - - - Saving checks project access; a new project is created only when its first trace arrives. Confirm that LangSmith is selected and tracing is enabled. Then run the app again and check the exact project name you configured. +**Used to track conversation title generation** - Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NameLangSmith Tool
user\_idextra.metadata.user_id
generate\_namename
start\_timestart\_time
end\_timeend\_time
inputsinputs
outputsoutputs
metadataextra.metadata
+**Generate Name Trace Info** - For a private-network endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - +* conversation\_id - Conversation ID +* inputs - Input data +* outputs - Generated conversation name +* start\_time - Start time +* end\_time - End time +* tenant\_id - Tenant ID +* Metadata + * conversation\_id - Conversation ID + * tenant\_id - Tenant ID diff --git a/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx index fc482102e..961fc4611 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,70 +1,569 @@ --- title: Integrate with Opik sidebarTitle: Opik -description: Connect a Dify app to Opik, verify new traces, and choose which Agent data to send --- -## Connect Your App -Get an API key for hosted Opik, or use your own Opik instance. See [Opik's Dify integration guide](https://www.comet.com/docs/opik/integrations/dify) for account setup. For a named workspace on your own server, ask its administrator which name to use. +### What is Opik -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Opik**, click **Config** and enter the connection details: +Opik is an open-source platform designed for evaluating, testing, and monitoring large language model (LLM) applications. Developed by Comet, it aims to facilitate more intuitive collaboration, testing, and monitoring of LLM-based applications. -| Field | Required | Value | -|:------|:---------|:------| -| **API Key** | For hosted Opik | Your account API key. Leave blank only if your server uses no authentication. | -| **Project** | No | The project name; Opik creates it on the first trace. If blank, Dify uses `Default Project`. | -| **Workspace** | No | An existing workspace. If blank, Dify uses the account default, or `default` for an unauthenticated open-source server. | -| **Url** | No | Defaults to `https://www.comet.com/opik/api/`. A custom HTTP(S) URL must end in `/api/`. | + +For more details, please refer to [Opik](https://www.comet.com/site/products/opik/). + -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Opik replaces the current selection. +--- -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Url** is unchanged. Re-enter them if you change the destination. +### How to Configure Opik -## What Dify Sends +For hosted Opik, follow the account and API key steps below. For a self-hosted instance without authentication, you can leave **API Key** blank. -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +#### 1. Register/Login to [Opik](https://www.comet.com/signup?from=llm) -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. +#### 2. Get your Opik API Key -In Opik, open an LLM span to inspect a model call's captured inputs and outputs. Token counts and USD costs appear in its usage and cost fields when available. +Retrieve your Opik API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: -### Include Agent Calls and Content + + ![Opik API Key](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) + - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +#### 3. Integrate Opik with Dify + +Configure Opik in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + ![Tracing App Performance](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) + + +After clicking configure, enter your **API Key** if required and the **project name**. A blank project uses `Default Project`; a new project is created on the first trace. **Workspace** can be left blank to use the account's default workspace. For self-hosted Opik, set **Url** to its API base URL ending in `/api/` (the default is `https://www.comet.com/opik/api/`), then save. + + + ![Configure Opik](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) + + +Once successfully saved, you can view the monitoring status on the current page. + +### View Monitoring Data in Opik + +Once configured, you can debug or use the Dify application as usual. New runs can be monitored in Opik; earlier usage history is not backfilled. -Under **Agent data capture** in the app's tracing settings: + + ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) + -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. +When you switch to Opik, you can view detailed operation logs of Dify applications in the dashboard. + + + ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) + + +Detailed LLM operation logs through Opik will help you optimize the performance of your Dify application. + + + ![Viewing Application Data in Opik](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) + -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### **Workflow/Chatflow Trace Information** + +**Used to track workflows and chatflows** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowOpik Trace
workflow_run_idid
user_idmetadata.user_id
workflowname
start_timestart_time
end_timeend_time
inputsinput
outputsoutput
Model token consumption (LLM calls)usage
metadatametadata
errorerror_info
Session IDthread_id (trace)
+**Workflow Trace Info** + +- workflow_id - Unique identifier of the workflow +- conversation_id - Conversation ID +- workflow_run_id - ID of the current run +- tenant_id - Tenant ID +- elapsed_time - Time taken for the current run +- status - Run status +- version - Workflow version +- total_tokens - Total tokens used in the current run +- file_list - List of processed files +- triggered_from - Source that triggered the current run +- workflow_run_inputs - Input data for the current run +- workflow_run_outputs - Output data for the current run +- error - Errors encountered during the current run +- query - Query used during the run +- workflow_app_log_id - Workflow application log ID +- message_id - Associated message ID +- start_time - Start time of the run +- end_time - End time of the run +- workflow node executions - Information about workflow node executions +- Metadata + - workflow_id - Unique identifier of the workflow + - conversation_id - Conversation ID + - workflow_run_id - ID of the current run + - tenant_id - Tenant ID + - elapsed_time - Time taken for the current run + - status - Run status + - version - Workflow version + - total_tokens - Total tokens used in the current run + - file_list - List of processed files + - triggered_from - Source that triggered the current run + +#### **Message Trace Information** + +**Used to track LLM-related conversations** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChatOpik Trace
message_idid
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time
end_timeend_time
inputsinput
outputsoutput
Model token consumption (LLM calls)usage
metadatametadata
Session IDthread_id (trace)
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- end_user_session_id - User session ID +- conversation_model - Conversation mode +- message_tokens - Number of tokens in the message +- answer_tokens - Number of tokens in the answer +- total_tokens - Total number of tokens in the message and answer +- error - Error information +- inputs - Input data +- outputs - Output data +- file_list - List of processed files +- start_time - Start time +- end_time - End time +- conversation_mode - Conversation mode +- Metadata + - conversation_id - Conversation ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Moderation Trace Information** + +**Used to track conversation moderation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationOpik Tool
user_idmetadata.user_id
moderationname
start_timestart_time
end_timeend_time
inputsinput
action, flaggedoutput
metadatametadata
+**Moderation Trace Info** + +- message_id - Message ID +- user_id: User ID +- workflow_app_log_id - Workflow application log ID +- inputs - Moderation input data +- message_data - Message data +- flagged - Whether the content is flagged for attention +- action - Specific actions taken +- preset_response - Preset response +- start_time - Moderation start time +- end_time - Moderation end time +- Metadata + - message_id - Message ID + - action - Specific actions taken + - preset_response - Preset response + +#### **Suggested Question Trace Information** + +**Used to track suggested questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionOpik Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinput
suggested_questionoutput
metadatametadata
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- inputs - Input content +- outputs - Output content +- start_time - Start time +- end_time - End time +- total_tokens - Number of tokens +- status - Message status +- error - Error information +- from_account_id - ID of the sending account +- agent_based - Whether the message is agent-based +- from_source - Message source +- model_provider - Model provider +- model_id - Model ID +- suggested_question - Suggested question +- level - Status level +- status_message - Status message +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Dataset Retrieval Trace Information** + +**Used to track knowledge base retrieval** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalOpik Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinput
documentsoutput
metadatametadata
message_idtrace_id
+**Dataset Retrieval Trace Info** + +- message_id - Message ID +- inputs - Input content +- documents - Document data +- start_time - Start time +- end_time - End time +- message_data - Message data +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Tool Trace Information** -## Verify a New Trace +**Used to track tool invocation** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Opik**. Select the configured workspace and project if the link opens the console. -3. Find the new trace by its run time and open it to inspect its spans. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolOpik Tool
user_idmetadata.user_id
tool_namename
start_timestart_time
end_timeend_time
tool_inputsinput
tool_outputsoutput
metadatametadata
+#### **Tool Trace Info** -Traces may take time to appear after the run finishes. +- message_id - Message ID +- tool_name - Tool name +- start_time - Start time +- end_time - End time +- tool_inputs - Tool inputs +- tool_outputs - Tool outputs +- message_data - Message data +- error - Error information, if any +- inputs - Inputs for the message +- outputs - Outputs of the message +- tool_config - Tool configuration +- time_cost - Time cost +- tool_parameters - Tool parameters +- file_url - URL of the associated file +- Metadata + - message_id - Message ID + - tool_name - Tool name + - tool_inputs - Tool inputs + - tool_outputs - Tool outputs + - tool_config - Tool configuration + - time_cost - Time cost + - error - Error information, if any + - tool_parameters - Tool parameters + - message_file_id - Message file ID + - created_by_role - Role of the creator + - created_user_id - User ID of the creator -## Troubleshooting +**Generate Name Trace Information** - - - Saving checks workspace access; Opik creates the project on its first trace. Confirm that Opik is selected and tracing is enabled. In Opik, open the configured workspace and project. Then run the app again. +**Used to track conversation title generation** - Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NameOpik Tool
user_idmetadata.user_id
generate_namename
start_timestart_time
end_timeend_time
inputsinput
outputsoutput
metadatametadata
+**Generate Name Trace Info** - For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - +- conversation_id - Conversation ID +- inputs - Input data +- outputs - Generated conversation name +- start_time - Start time +- end_time - End time +- tenant_id - Tenant ID +- Metadata + - conversation_id - Conversation ID + - tenant_id - Tenant ID diff --git a/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index 246cd5d84..6e3efa356 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,73 +1,599 @@ --- title: Integrate with Phoenix sidebarTitle: Phoenix -description: Connect a Dify app to Phoenix, verify new traces, and choose which Agent data to send --- -## Connect Your App -Use a Phoenix instance your Dify services can reach, either self-hosted or Phoenix Cloud. If it requires authentication, get an [API key](https://arize.com/docs/phoenix/settings/api-keys) that can read projects and send traces. To connect Arize instead, follow the [Arize integration](/en/self-host/use-dify/monitor/integrations/integrate-arize). +### What is Phoenix -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Phoenix**, click **Config** and enter the connection details: +[Arize Phoenix](https://arize.com/phoenix/) is the open-source, OpenTelemetry-based platform from [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) for observability, evaluation, prompt engineering, and experimentation with LLM workflows and agents. -| Field | Required | Value | -|:------|:---------|:------| -| **API Key** | When authentication is enabled | The key for your instance or Phoenix Cloud space. Leave blank for an unauthenticated server. | -| **Project** | Yes | The destination project name. | -| **Endpoint** | No | Your Phoenix base URL. Replace the default `https://app.phoenix.arize.com` with your Cloud space or self-hosted instance URL, including any path prefix. | +Run Phoenix locally during development, self-host it on your own infrastructure (a single container is enough to start), or use Arize's hosted [Phoenix Cloud](#how-to-configure-phoenix-cloud). -For Phoenix Cloud, copy your space's hostname, such as `https://app.phoenix.arize.com/s/`. See [Find Your Phoenix Endpoint](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint) for where to find it. Enter the base URL without `/v1/traces`; Dify adds that path. +If you need the full-featured platform built for production teams, AI-native companies, and enterprises, set up [Arize AX](https://arize.com/products/ax/) through the [Arize integration](/en/self-host/use-dify/monitor/integrations/integrate-arize) instead. -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Phoenix replaces the current selection. +Once traces are flowing, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/) for how to use them to debug failures, evaluate agent behavior, and monitor model quality. -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Endpoint** is unchanged. Re-enter them if you change the destination. +### How to Configure Phoenix -## What Dify Sends +For a self-hosted Phoenix instance without authentication, skip the account and API key steps below and leave **API Key** blank. -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +#### 1. Register/Login to [Phoenix](https://app.arize.com/auth/phoenix/signup) -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. +#### 2. Get your Phoenix API Key -In Phoenix, open a model span to inspect its captured inputs and outputs and available token counts. Dify doesn't fill Phoenix's built-in cost fields. +Retrieve your Phoenix API Key from the user menu at the top-right. Click on **API Key**, then on the API Key to copy it: -### Include Agent Calls and Content + + ![Phoenix API Key](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) + - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +#### 3. Integrate Phoenix with Dify + +Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + ![Tracing App Performance](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +After clicking configure, enter the **project name**, an **API Key** if authentication is enabled, and your Phoenix instance's base URL in **Endpoint**, then save. Do not append `/v1/traces`; Dify adds the ingestion path. + + + ![Configure Phoenix](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + + +Once successfully saved, you can view the monitoring status on the current page. + + + ![Configure Phoenix](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + + +### How to Configure Phoenix Cloud + +#### 1. Register/Login to [Phoenix Cloud](https://app.arize.com/auth/phoenix/signup) + +#### 2. Create your Phoenix Space + +You can create your Phoenix Space from the user menu at the top-right. Click on **Create Space**, then provide a unique URL identifier for your space: + + + ![Phoenix Cloud Create Space](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) + + +Once successfully saved, you can view the space status on the overview page. + + + ![Phoenix Cloud Space Overview](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) + + +#### 3. Create your Phoenix API Key + +After launching your space, you can create your Phoenix API Key from the **Settings** option in the user menu at the bottom-left. Click on **System Key**, then provide a name for your Phoenix API Key: + + + ![Phoenix Cloud API Key](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) + + +#### 4. Integrate Phoenix Cloud with Dify + +Configure Phoenix in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. + + + ![Tracing App Performance](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +After clicking configure, paste the **API Key** and **project name**, and enter the full Phoenix Cloud space URL in **Endpoint** (for example, `https://app.phoenix.arize.com/s/`), then save. + + + ![Configure Phoenix](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + -Under **Agent data capture** in the app's tracing settings: +Once successfully saved, you can view the monitoring status on the current page. -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. + + ![Configure Phoenix](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### **Workflow/Chatflow Trace Information** + +**Used to track workflows and chatflows** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowPhoenix Trace
workflow_run_idspan_id
user_idmetadata.user_id
workflowname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
Model token consumption (LLM calls)llm.token_count.prompt / completion / total
metadatametadata
errorstatus.code / status.message
Session IDsession.id
+**Workflow Trace Info** + +- workflow_id - Unique identifier of the workflow +- conversation_id - Conversation ID +- workflow_run_id - ID of the current run +- tenant_id - Tenant ID +- elapsed_time - Time taken for the current run +- status - Run status +- version - Workflow version +- total_tokens - Total tokens used in the current run +- file_list - List of processed files +- triggered_from - Source that triggered the current run +- workflow_run_inputs - Input data for the current run +- workflow_run_outputs - Output data for the current run +- error - Errors encountered during the current run +- query - Query used during the run +- workflow_app_log_id - Workflow application log ID +- message_id - Associated message ID +- start_time - Start time of the run +- end_time - End time of the run +- workflow node executions - Information about workflow node executions +- Metadata + - workflow_id - Unique identifier of the workflow + - conversation_id - Conversation ID + - workflow_run_id - ID of the current run + - tenant_id - Tenant ID + - elapsed_time - Time taken for the current run + - status - Run status + - version - Workflow version + - total_tokens - Total tokens used in the current run + - file_list - List of processed files + - triggered_from - Source that triggered the current run + +#### **Message Trace Information** + +**Used to track LLM-related conversations** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChatPhoenix Trace
message_idspan_id
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
Model token consumption (LLM calls)llm.token_count.prompt / completion / total
metadatametadata
Session IDsession.id
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- end_user_session_id - User session ID +- conversation_model - Conversation mode +- message_tokens - Number of tokens in the message +- answer_tokens - Number of tokens in the answer +- total_tokens - Total number of tokens in the message and answer +- error - Error information +- inputs - Input data +- outputs - Output data +- file_list - List of processed files +- start_time - Start time +- end_time - End time +- conversation_mode - Conversation mode +- Metadata + - conversation_id - Conversation ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Moderation Trace Information** + +**Used to track conversation moderation** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationPhoenix Tool
user_idmetadata.user_id
moderationname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
action, flaggedoutput.value
metadatametadata
+**Moderation Trace Info** + +- message_id - Message ID +- user_id: User ID +- workflow_app_log_id - Workflow application log ID +- inputs - Moderation input data +- message_data - Message data +- flagged - Whether the content is flagged for attention +- action - Specific actions taken +- preset_response - Preset response +- start_time - Moderation start time +- end_time - Moderation end time +- Metadata + - message_id - Message ID + - action - Specific actions taken + - preset_response - Preset response + +#### **Suggested Question Trace Information** + +**Used to track suggested questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionPhoenix Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
suggested_questionoutput.value
metadatametadata
+**Message Trace Info** + +- message_id - Message ID +- message_data - Message data +- inputs - Input content +- outputs - Output content +- start_time - Start time +- end_time - End time +- total_tokens - Number of tokens +- status - Message status +- error - Error information +- from_account_id - ID of the sending account +- agent_based - Whether the message is agent-based +- from_source - Message source +- model_provider - Model provider +- model_id - Model ID +- suggested_question - Suggested question +- level - Status level +- status_message - Status message +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - workflow_run_id - Workflow run ID + - from_source - Message source + +#### **Dataset Retrieval Trace Information** + +**Used to track knowledge base retrieval** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalPhoenix Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
documentsoutput.value
metadatametadata
message_idparent_span_id
+**Dataset Retrieval Trace Info** + +- message_id - Message ID +- inputs - Input content +- documents - Document data +- start_time - Start time +- end_time - End time +- message_data - Message data +- Metadata + - message_id - Message ID + - ls_provider - Model provider + - ls_model_name - Model ID + - status - Message status + - from_end_user_id - ID of the sending user + - from_account_id - ID of the sending account + - agent_based - Whether the message is agent-based + - workflow_run_id - Workflow run ID + - from_source - Message source -## Verify a New Trace +#### **Tool Trace Information** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Phoenix** to open the configured project. -3. Find the new trace by its run time and open it to inspect its child spans. +**Used to track tool invocation** -Traces may take time to appear after the run finishes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolPhoenix Tool
user_idmetadata.user_id
tool_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
tool_inputsinput.value
tool_outputsoutput.value
metadatametadata
+#### **Tool Trace Info** -## Troubleshooting +- message_id - Message ID +- tool_name - Tool name +- start_time - Start time +- end_time - End time +- tool_inputs - Tool inputs +- tool_outputs - Tool outputs +- message_data - Message data +- error - Error information, if any +- inputs - Inputs for the message +- outputs - Outputs of the message +- tool_config - Tool configuration +- time_cost - Time cost +- tool_parameters - Tool parameters +- file_url - URL of the associated file +- Metadata + - message_id - Message ID + - tool_name - Tool name + - tool_inputs - Tool inputs + - tool_outputs - Tool outputs + - tool_config - Tool configuration + - time_cost - Time cost + - error - Error information, if any + - tool_parameters - Tool parameters + - message_file_id - Message file ID + - created_by_role - Role of the creator + - created_user_id - User ID of the creator - - - Saving confirms access to read projects; it does not send a trace. Confirm that Phoenix is selected and tracing is enabled. Then run the app again and check the configured project. +**Generate Name Trace Information** - Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. +**Used to track conversation title generation** - For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NamePhoenix Tool
user_idmetadata.user_id
generate_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
metadatametadata
+**Generate Name Trace Info** -For help evaluating the traces you collect, see Arize's [agent evaluation guide](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) and [LLM evaluation guide](https://arize.com/resources/llm-evaluation/). +- conversation_id - Conversation ID +- inputs - Input data +- outputs - Generated conversation name +- start_time - Start time +- end_time - End time +- tenant_id - Tenant ID +- Metadata + - conversation_id - Conversation ID + - tenant_id - Tenant ID diff --git a/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx index c58441fc0..dad5e5507 100644 --- a/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/en/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -4,70 +4,345 @@ sidebarTitle: W&B Weave description: Send traces from Dify applications to W&B Weave for LLM observability --- -## Connect Your App + + **Prerequisites**: Dify v1.3.1 or later. + -Create a [W&B project](https://docs.wandb.ai/models/track/project-page#create-a-project) that your [API key](https://wandb.ai/authorize) can write to before configuring Dify. For a team project, use that team as the **Entity**. +### What is W&B Weave -In the Dify app, open **Monitoring** > **Tracing app performance**. For **Weave**, click **Config** and enter the connection details: +Weights & Biases (W&B) Weave is a framework for tracking, experimenting with, evaluating, deploying, and improving LLM-based applications. Designed for flexibility and scalability, Weave supports every stage of your LLM application development workflow. -| Field | Required | Value | -|:------|:---------|:------| -| **API Key** | Yes | Your W&B API key. | -| **Project** | Yes | An existing, writable project. You can enter `entity/project` here and leave **Entity** blank. | -| **Entity** | No | The W&B team or user. If blank, Dify resolves the API key's default entity. | -| **Endpoint** | No | The Weave trace server. Defaults to `https://trace.wandb.ai`; HTTPS is required. | -| **Host** | No | The W&B API server. Defaults to `https://api.wandb.ai`; HTTP(S) is accepted. | + + For more details, please refer to [Weave](https://docs.wandb.ai/weave). + -For a custom deployment, ask its administrator for the trace-server **Endpoint** and W&B API **Host**. Keep any path prefix they provide. +### How to Configure Weave -Review [what Dify sends](#what-dify-sends), then click **Save & Enable**. Each app has one active tracing provider; selecting Weave replaces the current selection. +#### 1. Register/Login -Saved credentials are hidden when you edit. Leave them blank to keep their saved values while **Host** and **Endpoint** are unchanged. Re-enter them if you change either address. +Register/Login to [W&B Weave](https://wandb.ai/signup) and get your API key. Then, copy your API key from [here](https://wandb.ai/authorize). -## What Dify Sends +#### 2. Integrate W&B Weave with Dify -A trace records an app execution as timed operations called *spans*. Each span includes its status and any error. Dify also sends captured inputs and outputs, model usage, and identifying metadata such as message, workflow, and node IDs. +Configure Weave in the Dify application. Open the application you need to monitor, open **Monitoring** in the side menu, and select **Tracing app performance** on the page. -For a Workflow, inspect its node spans, including loop and iteration groups. Chat traces include the model call under the message. In a Chatflow trace, the workflow sits under the message. + + ![Configure Weave in the Dify Application](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) + -In Weave, open a model call to inspect its captured inputs and outputs. Available token counts appear in the call's per-model usage. Dify doesn't fill Weave's built-in cost field. +After clicking configure, paste the **API Key** and an existing, writable **project name**, and optionally specify the **W&B entity**. If the entity is blank, Dify uses the API key's default entity, which may be a team. Save the configuration. -### Include Agent Calls and Content + + ![Configure, Paste the API Key and Project Name, Also Specify the W&B](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) + - -Tracing for Agent apps and the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent) is off by default. Ask your deployment administrator to set both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for where to set them. - +Once successfully saved, you can view the monitoring status on the current page. + + + ![Once Successfully Saved, You Can View the Monitoring Status on the Current Page](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) + + +### View Monitoring Data in Weave + +Once configured, the debug or production data from applications within Dify can be monitored in Weave. -Under **Agent data capture** in the app's tracing settings: + + ![Once Configured, the Debug or Production Data from Applications Within Dify Can](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) + -- **Capture Agent internals**: Keep this on to inspect the Agent's internal model and tool calls when debugging its decisions. Turn it off to omit those internal calls while keeping the Agent run or workflow node itself. -- **Capture content**: Turn this on only if the monitoring service should receive inputs and outputs from these runs. With it off, timings, token information, and status remain available. +When you switch to Weave, you can view detailed operation logs of Dify applications in the dashboard. + + + ![When You Switch to Weave, You Can View Detailed Operation Logs of Dify](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) + + +Detailed LLM operation logs through Weave will help you optimize the performance of your Dify application. -These controls apply to Agent apps and Workflow or Chatflow apps that contain the new Agent node. For those workflows, **Capture content** also controls the other nodes' inputs and outputs. Other apps can still send inputs and outputs; leave tracing disabled if you can't send that content to the monitoring service. +After saving and enabling tracing, run the app again and check for a new trace in the monitoring service. Delivery is asynchronous; saving the configuration alone does not confirm that a trace has arrived. + +For Agent apps and workflows using the [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent), enable both `OPS_AGENT_TRACE_ENABLED=true` and `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` in your deployment. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery). **Capture content** is off by default for these apps and controls inputs and outputs across the whole workflow. Other apps can still send inputs and outputs. -The new Agent node uses the containing Workflow or Chatflow app's tracing settings. Agent calls inside a workflow tool aren't included in the parent Agent's trace. +### Monitoring Data List + +Dify exports a hierarchy of operations: a message contains an `llm` call, and a Chatflow message contains its workflow and node operations. Provider trace and span IDs are derived from Dify identifiers rather than copied directly from database IDs. Native token usage is reported on model calls only. + +The detail lists below describe Dify's source records and metadata. Only the relevant, available values are exported; the raw records are not sent in full. + +#### **Workflow/Chatflow Trace Information** + +**Used to track workflows and chatflows** + +| Workflow | Weave Trace | +| ---------------------------------------- | ---------------------------- | +| workflow_run_id | id | +| user_id | attributes.user_id | +| workflow | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| Model token consumption (LLM calls) | summary.usage (per model) | +| metadata | attributes | +| error | exception | +| Session ID | thread_id | +| Parent span (when present) | parent_id | + +**Workflow Trace Info** + +* workflow_id - Unique identifier of the workflow +* conversation_id - Conversation ID +* workflow_run_id - ID of the current run +* tenant_id - Tenant ID +* elapsed_time - Time taken for the current run +* status - Run status +* version - Workflow version +* total_tokens - Total tokens used in the current run +* file_list - List of processed files +* triggered_from - Source that triggered the current run +* workflow_run_inputs - Input data for the current run +* workflow_run_outputs - Output data for the current run +* error - Errors encountered during the current run +* query - Query used during the run +* workflow_app_log_id - Workflow application log ID +* message_id - Associated message ID +* start_time - Start time of the run +* end_time - End time of the run +* workflow node executions - Information about workflow node executions +* Metadata + * workflow_id - Unique identifier of the workflow + * conversation_id - Conversation ID + * workflow_run_id - ID of the current run + * tenant_id - Tenant ID + * elapsed_time - Time taken for the current run + * status - Run status + * version - Workflow version + * total_tokens - Total tokens used in the current run + * file_list - List of processed files + * triggered_from - Source that triggered the current run + +#### **Message Trace Information** + +**Used to track LLM-related conversations** + +| Chat | Weave Trace | +| -------------------------------- | ---------------------------- | +| message_id | id | +| end_user_session_id | attributes.end_user_session_id | +| message | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| Model token consumption (LLM calls) | summary.usage (per model) | +| metadata | attributes | +| error | exception | +| Session ID | thread_id | + +**Message Trace Info** + +* message_id - Message ID +* message_data - Message data +* end_user_session_id - User session ID +* conversation_model - Conversation mode +* message_tokens - Number of tokens in the message +* answer_tokens - Number of tokens in the answer +* total_tokens - Total number of tokens in the message and answer +* error - Error information +* inputs - Input data +* outputs - Output data +* file_list - List of processed files +* start_time - Start time +* end_time - End time +* conversation_mode - Conversation mode +* Metadata + * conversation_id - Conversation ID + * ls_provider - Model provider + * ls_model_name - Model ID + * status - Message status + * from_end_user_id - ID of the sending user + * from_account_id - ID of the sending account + * agent_based - Whether the message is agent-based + * workflow_run_id - Workflow run ID + * from_source - Message source + +#### **Moderation Trace Information** + +**Used to track conversation moderation** + +| Moderation | Weave Trace | +| ------------- | -------------------- | +| user_id | attributes.user_id | +| moderation | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| action, flagged | output | +| metadata | attributes | +| message_id | parent_id | + +**Moderation Trace Info** + +* message_id - Message ID +* user_id: User ID +* workflow_app_log_id - Workflow application log ID +* inputs - Moderation input data +* message_data - Message data +* flagged - Whether the content is flagged for attention +* action - Specific actions taken +* preset_response - Preset response +* start_time - Moderation start time +* end_time - Moderation end time +* Metadata + * message_id - Message ID + * action - Specific actions taken + * preset_response - Preset response + +#### **Suggested Question Trace Information** + +**Used to track suggested questions** + +| Suggested Question | Weave Trace | +| ---------------------- | -------------------- | +| user_id | attributes.user_id | +| suggested_question | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| suggested_question | output | +| metadata | attributes | +| message_id | parent_id | + +**Message Trace Info** + +* message_id - Message ID +* message_data - Message data +* inputs - Input content +* outputs - Output content +* start_time - Start time +* end_time - End time +* total_tokens - Number of tokens +* status - Message status +* error - Error information +* from_account_id - ID of the sending account +* agent_based - Whether the message is agent-based +* from_source - Message source +* model_provider - Model provider +* model_id - Model ID +* suggested_question - Suggested question +* level - Status level +* status_message - Status message +* Metadata + * message_id - Message ID + * ls_provider - Model provider + * ls_model_name - Model ID + * status - Message status + * from_end_user_id - ID of the sending user + * from_account_id - ID of the sending account + * workflow_run_id - Workflow run ID + * from_source - Message source + +#### **Dataset Retrieval Trace Information** + +**Used to track knowledge base retrieval** + +| Dataset Retrieval | Weave Trace | +| --------------------- | -------------------- | +| user_id | attributes.user_id | +| dataset_retrieval | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| documents | output | +| metadata | attributes | +| message_id | parent_id | + +**Dataset Retrieval Trace Info** + +* message_id - Message ID +* inputs - Input content +* documents - Document data +* start_time - Start time +* end_time - End time +* message_data - Message data +* Metadata + * message_id - Message ID + * ls_provider - Model provider + * ls_model_name - Model ID + * status - Message status + * from_end_user_id - ID of the sending user + * from_account_id - ID of the sending account + * agent_based - Whether the message is agent-based + * workflow_run_id - Workflow run ID + * from_source - Message source + +#### **Tool Trace Information** + +**Used to track tool invocation** + +| Tool | Weave Trace | +| --------------------- | -------------------- | +| user_id | attributes.user_id | +| tool_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| tool_inputs | inputs | +| tool_outputs | output | +| metadata | attributes | +| message_id | parent_id | -## Verify a New Trace +#### **Tool Trace Info** -1. Run a new request in your Dify app and let it finish. -2. In **Tracing app performance**, click **View** for **Weave** to open the configured project. -3. Find the new call by its run time and open it to inspect its child calls. +* message_id - Message ID +* tool_name - Tool name +* start_time - Start time +* end_time - End time +* tool_inputs - Tool inputs +* tool_outputs - Tool outputs +* message_data - Message data +* error - Error information, if any +* inputs - Inputs for the message +* outputs - Outputs of the message +* tool_config - Tool configuration +* time_cost - Time cost +* tool_parameters - Tool parameters +* file_url - URL of the associated file +* Metadata + * message_id - Message ID + * tool_name - Tool name + * tool_inputs - Tool inputs + * tool_outputs - Tool outputs + * tool_config - Tool configuration + * time_cost - Time cost + * error - Error information, if any + * tool_parameters - Tool parameters + * message_file_id - Message file ID + * created_by_role - Role of the creator + * created_user_id - User ID of the creator -Traces may take time to appear after the run finishes. +**Generate Name Trace Information** -## Troubleshooting +**Used to track conversation title generation** - - - Saving checks that the project exists, is writable, and that the trace server is accessible. Confirm that Weave is selected and tracing is enabled. In Weave, open the configured entity and project. Then run the app again. +| Generate Name | Weave Trace | +| ----------------- | -------------------- | +| user_id | attributes.user_id | +| generate_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| metadata | attributes | - Ask your administrator to check worker logs and the [trace delivery queue](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) if the new run is still missing. - - - The address must be reachable from Dify's API and workers. In a container, `localhost` points to that container, so use the monitoring server's reachable hostname instead. +**Generate Name Trace Info** - For a private HTTP endpoint, ask your administrator to check the [SSRF proxy allowlist](/en/self-host/deploy/configuration/environments#ssrf-proxy) and allow only the required destination. - - +* conversation_id - Conversation ID +* inputs - Input data +* outputs - Generated conversation name +* start_time - Start time +* end_time - End time +* tenant_id - Tenant ID +* Metadata + * conversation_id - Conversation ID + * tenant_id - Tenant ID diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index c19a6480d..8550a0cc5 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -1,82 +1,399 @@ --- title: Alibaba Cloud Monitor の統合 -sidebarTitle: Alibaba Cloud Monitor -description: Dify のトレースを OpenTelemetry 経由で Alibaba Cloud Monitor（ARMS）に送信します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-aliyun) を参照してください。 -## アプリの接続 +## Alibaba Cloud Monitor とは -[Alibaba Cloud の接続手順](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin) に沿って、デプロイ先の管理者に License Key と HTTP トレース URL を確認します。Dify の各サービスから接続できるリージョンとネットワークアドレスを選んでもらってください。 +Alibaba Cloud は、Dify アプリケーションのワンクリック監視、トレース、評価を可能にする、フルマネージドかつメンテナンス不要のオブザーバビリティプラットフォームを提供します。 -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**クラウドモニター** の **設定** をクリックし、接続情報を入力してください。 + + Alibaba Cloud Monitor は、[LoongSuite](https://github.com/alibaba/loongsuite-python-agent) エージェントやオープンソースの OpenTelemetry エージェントを通じて、Python/Golang/Java アプリケーションをネイティブにサポートします。Dify LLM アプリケーションのワンクリック監視に加え、非侵入型エージェントによる Dify コンポーネントおよびその上下流依存関係のエンドツーエンドの可観測性もサポートします。 + + 詳細は [Cloud Monitor ドキュメント](https://www.alibabacloud.com/help/en/cms/cloudmonitor-1-0/product-overview/what-is-cloudmonitor?spm=a3c0i.63551.2277339270.1.76c7112eeKEvSr) をご参照ください。 + -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **License Key** | はい | コレクタの認証キー。エンドポイントとは別に入力します。 | -| **Endpoint** | はい | コレクタの HTTP(S) ベース URL。ポートを明示的に指定できます。 | -| **App Name** | はい | ARMS コンソールに表示するアプリケーション名。任意の名前を指定します。 | +## Alibaba Cloud Monitor の設定方法 -HTTP トレース URL の `/adapt_` より前の部分を **Endpoint** に入力します。認証用の API トークンは **License Key** に入力してください。たとえば、次の URL では以下のように指定します。 +### 1. Alibaba Cloud のエンドポイントとライセンスキーの取得 -```text -https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces -``` +1. [ARMS コンソール](https://account.alibabacloud.com/login/login.htm?spm=5176.12901015-2.0.0.68d74b84XRatpU)にログインし、左側のナビゲーションバーで **Integration Center** をクリックします。 +2. **Server-side Applications** エリアで **OpenTelemetry** カードをクリックします。 +3. 表示された **OpenTelemetry** パネルで、エクスポートプロトコルとして **HTTP** を選択します。実際のデプロイに応じて接続方法とリージョンを選択します。 -- **Endpoint**: `https://tracing-analysis-dc-hz.aliyuncs.com` -- **License Key**: `example-key` + + ![Alibaba Cloud アクセスポイントの取得](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/get_endpoint.png) + -HTTP エンドポイントにポートが含まれている場合は、そのまま指定してください。`8090` などの gRPC ポートは使用できません。 +4. **Public Endpoint** と **Authentication Token (License Key)** を保存します。 -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Cloud Monitor を選ぶと、現在の選択が置き換わります。 + + **Endpoint** には HTTP(S) のベース URL を指定します。HTTP コレクターにポート指定が必要な場合は、そのポートを残してください。トークンは **License Key** に別途入力します。`adapt_` や取り込みパスを含めず、gRPC ポートの `8090` は使用しないでください。OTLP/HTTP の取り込み URL は Dify が組み立てます。 + -保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 +### 2. Dify で Cloud Monitor を設定 -## Dify が送信するデータ + + Dify v1.6.0 以上が必要です。 + -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +1. Dify コンソールにログインし、監視したいアプリケーションに移動します。 +2. 左側のナビゲーションバーで **Monitoring** を開きます。 +3. **Tracing app performance** をクリックし、**Cloud Monitor** エリアで **Configure** をクリックします。 -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 + + ![Alibaba Cloud Monitor の設定](https://dify-public-resources.oss-cn-hangzhou.aliyuncs.com/dify-doc/config_cms.png) + -Alibaba Cloud Monitor でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify はこのプラットフォームに標準で用意されている費用フィールドには値を設定しません。 +4. 表示されたダイアログで、手順 1 で取得した **License Key** と **Endpoint** を入力し、**App Name**（ARMS コンソールに表示されるアプリケーション名）をカスタマイズして **Save & Enable** をクリックします。 -### Agent の呼び出しと内容の収集 +## Alibaba Cloud Monitor での監視データの表示 - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - +設定後、Dify のアプリケーションからのデバッグまたは本番データは Cloud Monitor で監視できます。 + +### 方法 1: Dify アプリケーションから ARMS コンソールにジャンプ + +Dify コンソールでトレースが有効になっているアプリケーションを選択し、**Tracing Configuration** に移動して、**Cloud Monitor** エリアの **View** をクリックします。 -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +### 方法 2: ARMS コンソールで直接表示 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 +ARMS コンソールの **LLM Application Monitoring > Application List** ページで、対応する Dify アプリケーションに移動します。 + +## より多くのデータにアクセス + +Cloud Monitor は、Dify クラスターのさまざまなコンポーネントにアクセスしてエンドツーエンドのトレースを実現するマルチランゲージの非侵入型エージェントを提供します。 + +| Dify コンポーネント | エージェント | 詳細 | +|----------------|-------|---------| +| Nginx | OpenTelemetry Agent | [Nginx トレースに OpenTelemetry を使用](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx?spm=a2c63.l28256.help-menu-search-90275.d_1) | +| API | LoongSuite-Python Agent | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | +| Sandbox | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | +| Worker | OpenTelemetry Agent | [OpenTelemetry を介して Python アプリケーションデータを送信](https://www.alibabacloud.com/help/en/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications?spm=a2c63.p38356.help-menu-90275.d_2_0_5_0.18ee53a4EGoGuS) | +| Plugin-Daemon | LoongSuite-Go Agent | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +## 監視データリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 + +Cloud Monitor は、Dify の Workflow/Chatflow/Chat/Agent アプリケーションからデータを収集することをサポートしており、ワークフローおよびワークフローノードの実行詳細、モデル呼び出し、ツール呼び出し、知識取得、さまざまなプロセスノードの実行詳細、会話やユーザー情報などのメタデータをカバーしています。 + +### Workflow/Chatflow トレース情報 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowAlibaba Cloud Monitor Trace
workflow\_idワークフローの一意の識別子
conversation\_id会話 ID
workflow\_run\_idこの実行の ID
tenant\_idテナント ID
elapsed\_timeこの実行の所要時間
status実行ステータス
versionワークフローのバージョン
total\_tokensこの実行で使用されたトークンの総数
file\_list処理されたファイルのリスト
triggered\_fromこの実行をトリガーしたソース
workflow\_run\_inputsこの実行の入力データ
workflow\_run\_outputsこの実行の出力データ
errorこの実行中に発生したエラー
query実行時に使用されたクエリ
workflow\_app\_log\_idWorkflow アプリケーションログ ID
message\_id関連するメッセージ ID
start\_time実行開始時刻
end\_time実行終了時刻
+ +**ワークフロートレースメタデータ** + +* workflow\_id - ワークフローの一意の識別子 +* conversation\_id - 会話 ID +* workflow\_run\_id - この実行の ID +* tenant\_id - テナント ID +* elapsed\_time - この実行の所要時間 +* status - 実行ステータス +* version - ワークフローのバージョン +* total\_tokens - この実行で使用されたトークンの総数 +* file\_list - 処理されたファイルのリスト +* triggered\_from - トリガーソース + +### メッセージトレース情報 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MessageAlibaba Cloud Monitor Trace
message\_idメッセージ ID
message\_dataメッセージデータ
end\_user\_session\_idユーザーの session\_id
conversation\_model会話モデル
message\_tokensメッセージ内のトークン数
answer\_tokens回答内のトークン数
total\_tokensメッセージと回答のトークンの総数
errorエラー情報
inputs入力データ
outputs出力データ
file\_list処理されたファイルのリスト
start\_time開始時刻
end\_time終了時刻
conversation\_mode会話モード
+ +**メッセージトレースメタデータ** + +* conversation\_id - メッセージが属する会話の ID +* ls\_provider - モデルプロバイダー +* ls\_model\_name - モデル ID +* status - メッセージステータス +* from\_end\_user\_id - 送信ユーザーの ID +* from\_account\_id - 送信アカウントの ID +* agent\_based - エージェントベースかどうか +* workflow\_run\_id - ワークフロー実行 ID +* from\_source - メッセージソース +* message\_id - メッセージ ID + +### データセット取得トレース情報 -## 新しいトレースの確認 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalAlibaba Cloud Monitor Trace
message\_idメッセージ ID
inputs入力コンテンツ
documentsドキュメントデータ
start\_time開始時刻
end\_time終了時刻
message\_dataメッセージデータ
-1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**クラウドモニター** の **見る** をクリックして ARMS LLM コンソールを開きます。 -3. 入力したアプリケーション名を探します。実行時刻を手がかりに新しいトレースを見つけ、子のスパンを確認します。 +**データセット取得トレースメタデータ** -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +* message\_id - メッセージ ID +* ls\_provider - モデルプロバイダー +* ls\_model\_name - モデル ID +* status - メッセージステータス +* from\_end\_user\_id - 送信ユーザーの ID +* from\_account\_id - 送信アカウントの ID +* agent\_based - エージェントベースかどうか +* workflow\_run\_id - ワークフロー実行 ID +* from\_source - メッセージソース -## トラブルシューティング +### ツールトレース情報 - - - 保存時にはコレクタへのアクセスをテストしますが、実際のトレースは作成しません。Cloud Monitor が選択され、トレースが有効になっていることを確認してください。Alibaba Cloud Monitor で、Dify に設定した名前のアプリケーションを開き、アプリを再度実行します。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolAlibaba Cloud Monitor Trace
message\_idメッセージ ID
tool\_nameツール名
start\_time開始時刻
end\_time終了時刻
tool\_inputsツール入力
tool\_outputsツール出力
message\_dataメッセージデータ
errorエラー情報（該当する場合）
inputsメッセージの入力コンテンツ
outputsメッセージの回答コンテンツ
tool\_configツール設定
time\_costコスト時間
tool\_parametersツールパラメータ
file\_url関連ファイルの URL
- 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 +**ツールトレースメタデータ** - プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - +* message\_id - メッセージ ID +* tool\_name - ツール名 +* tool\_inputs - ツール入力 +* tool\_outputs - ツール出力 +* tool\_config - ツール設定 +* time\_cost - コスト時間 +* error - エラー情報 +* tool\_parameters - ツールパラメータ +* message\_file\_id - メッセージファイル ID +* created\_by\_role - 作成者の役割 +* created\_user\_id - 作成者のユーザーID \ No newline at end of file diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx index 00d53adc2..c0036195e 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,74 +1,504 @@ --- title: Arize の統合 -sidebarTitle: Arize -description: Dify アプリを Arize に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-arize) を参照してください。 -## アプリの接続 -Arize の **Settings** > **API Keys** で、API キーと現在の Space ID を取得します。詳細は [Arize クイックスタート](https://arize.com/docs/ax/quickstarts) を参照してください。送信先のプロジェクト名を決めておきます。Phoenix に接続する場合は、[Phoenix 連携](/ja/self-host/use-dify/monitor/integrations/integrate-phoenix) の手順に従ってください。 +### 1 Arize とは -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Arize** の **設定** をクリックし、接続情報を入力してください。 +[Arize AX](https://arize.com/products/ax/) は、[Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host) が提供するフル機能プラットフォームです。LLM やエージェント駆動型アプリケーションの可観測性、オンライン・オフライン評価、モニタリング、実験に対応します。本番運用チームや AI ネイティブ企業、エンタープライズ向けに設計されており、マネージドクラウドまたはエンタープライズ向けセルフホストでデプロイできます。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **API Key** | はい | データ取り込み権限を持つ Arize API キー。 | -| **Space ID** | はい | トレースの送信先となる Arize スペース。 | -| **プロジェクト** | はい | 送信先のプロジェクト名。 | -| **Endpoint** | いいえ | 既定値は `https://otlp.arize.com`。独自のコレクタには、管理者が指定するアドレスを使用します。 | +ローカル開発や実験、単一コンテナでのセルフホストに適したオープンソース構成が必要な場合は、代わりに [Phoenix 統合](/ja/self-host/use-dify/monitor/integrations/integrate-phoenix) を設定してください。 -独自の **Endpoint** は OTLP/gRPC に対応している必要があります。ホスト名とポートを管理者に確認してください。`/v1/traces` などの HTTP パスは含めません。 +トレースの送信が始まったら、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。障害のデバッグ、エージェント動作の評価、モデル品質のモニタリングにトレースを活用する方法を確認できます。 -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Arize を選ぶと、現在の選択が置き換わります。 +### 2 Arize の使い方 -保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、**API Key** と **Space ID** を空欄にすると保存済みの値を維持できます。エンドポイントを変更した場合は、両方を再入力してください。 +#### 1. Arize の[公式サイト](https://app.arize.com/auth/join)から登録し、ログインする。 -## Dify が送信するデータ +### 2. Arize API キーの取得 -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 + + ![Arize API キー](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) + -Arize でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify は Arize に標準で用意されている費用フィールドには値を設定しません。 +### 3. Arize と Dify を統合 -### Agent の呼び出しと内容の収集 +Dify アプリケーションで Arize を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - + + ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) + + +設定をクリックした後、**API Key**、**Space ID**、**プロジェクト** 名を入力して保存します。**Endpoint** のデフォルトは `https://otlp.arize.com` です。OTLP/gRPC コレクターを指定してください。URL のパスは使われません。HTTP の `/v1/traces` エンドポイントは指定しないでください。 + + + ![Arize の設定](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) + -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +保存に成功すると、現在のページで監視ステータスを確認できます。 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 + + ![Arize の設定](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) + -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +## モニタリングデータリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 + +### **ワークフロー/会話フロートラッキング情報** + +**ワークフローと会話フローの追跡に使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ワークフローArize トラッキング
workflow_run_idspan_id
user_idmetadata.user_id
workflowname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
モデルトークン消費量（LLM 呼び出し）llm.token_count.prompt / completion / total
metadatametadata
errorstatus.code / status.message
セッション IDsession.id
+**ワークフロートラッキング情報** + +- workflow_id - ワークフローの一意識別子 +- conversation_id - 会話 ID +- workflow_run_id - 現在の実行 ID +- tenant_id - テナント ID +- elapsed_time - 現在の実行にかかった時間 +- status - 実行ステータス +- version - ワークフローバージョン +- total_tokens - 現在の実行で使用されたトークン総数 +- file_list - 処理されたファイルのリスト +- triggered_from - 実行をトリガーしたソース +- workflow_run_inputs - 現在の実行の入力データ +- workflow_run_outputs - 現在の実行の出力データ +- error - 実行中に発生したエラー +- query - 実行中に使用されたクエリ +- workflow_app_log_id - Workflow アプリケーションログ ID +- message_id - 関連するメッセージ ID +- start_time - 実行開始時間 +- end_time - 実行終了時間 +- workflow node executions - ワークフローノードの実行情報 +- メタデータ + - workflow_id - ワークフローの一意識別子 + - conversation_id - 会話 ID + - workflow_run_id - 現在の実行 ID + - tenant_id - テナント ID + - elapsed_time - 現在の実行にかかった時間 + - status - 実行ステータス + - version - ワークフローバージョン + - total_tokens - 現在の実行で使用されたトークン総数 + - file_list - 処理されたファイルのリスト + - triggered_from - 実行をトリガーしたソース + +--- + +### **メッセージトラッキング情報** + +**LLM 関連の会話を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
チャットArize Trace
message_idspan_id
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
モデルトークン消費量（LLM 呼び出し）llm.token_count.prompt / completion / total
metadatametadata
セッション IDsession.id
+**メッセージトラッキング情報** -## 新しいトレースの確認 +- message_id - メッセージ ID +- message_data - メッセージデータ +- end_user_session_id - ユーザーセッション ID +- conversation_model - 会話モード +- message_tokens - メッセージ内のトークン数 +- answer_tokens - 回答内のトークン数 +- total_tokens - メッセージと回答のトークン総数 +- error - エラー情報 +- inputs - 入力データ +- outputs - 出力データ +- file_list - 処理されたファイルリスト +- start_time - 開始時間 +- end_time - 終了時間 +- conversation_mode - 会話モード +- メタデータ + - conversation_id - 会話 ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージソース -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**Arize** の **見る** をクリックします。ショートカットが使えない場合は、Arize のスペースとプロジェクトを直接開きます。 -3. 実行時刻を手がかりに新しいトレースを探し、開いて子のスパンを確認します。 +### **レビュー追跡情報** -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +**会話のレビューを追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
レビューArize Tool
user_idmetadata.user_id
"moderation"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
action, flaggedoutput.value
metadatametadata
+**レビュー追跡情報** + +- message_id - メッセージ ID +- user_id - ユーザーID +- workflow_app_log_id - Workflow アプリケーションログ ID +- inputs - レビュー入力データ +- message_data - メッセージデータ +- flagged - 注意が必要とマークされたかどうか +- action - 実施された具体的なアクション +- preset_response - プリセットレスポンス +- start_time - レビュー開始時間 +- end_time - レビュー終了時間 +- メタデータ + - message_id - メッセージ ID + - action - 実施されたアクション + - preset_response - プリセットレスポンス + +--- + +### **提案質問追跡情報** + +**提案質問を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
提案質問Arize Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
suggested_questionoutput.value
metadatametadata
+**提案質問追跡情報** + +- message_id - メッセージ ID +- message_data - メッセージデータ +- inputs - 入力データ +- outputs - 出力データ +- start_time - 開始時間 +- end_time - 終了時間 +- total_tokens - トークン総数 +- status - メッセージステータス +- error - エラー情報 +- from_account_id - 送信アカウント ID +- agent_based - エージェントベースかどうか +- from_source - メッセージの送信元 +- model_provider - モデルプロバイダー +- model_id - モデル ID +- suggested_question - 提案された質問 +- level - ステータスレベル +- status_message - ステータスメッセージ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- + +### **データセット検索追跡情報** + +**ナレッジベース検索を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
データセット検索Arize Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
documentsoutput.value
metadatametadata
message_idparent_span_id
+**データセット検索追跡情報** + +- message_id - メッセージ ID +- inputs - 入力データ +- documents - ドキュメントデータ +- start_time - 開始時間 +- end_time - 終了時間 +- message_data - メッセージデータ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- -## トラブルシューティング +### **ツール追跡情報** - - - 保存時にはコレクタへのアクセスをテストしますが、実際のトレースは作成しません。Arize が選択され、トレースが有効になっていることを確認してください。Arize で、Dify に設定したスペースとプロジェクトを開き、アプリを再度実行します。 +**ツールの呼び出しを追跡するために使用** - 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから gRPC コレクタに接続できる必要があります。管理者にホスト名、ポート、ネットワークアクセスの確認を依頼してください。`localhost` などのループバックアドレスは使用できません。到達可能なサーバーアドレスを指定してください。 - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ツールArize Tool
user_idmetadata.user_id
tool_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
tool_inputsinput.value
tool_outputsoutput.value
metadatametadata
+**ツール追跡情報** -収集したトレースの評価方法については、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。 +- message_id - メッセージ ID +- tool_name - ツール名 +- start_time - 開始時間 +- end_time - 終了時間 +- tool_inputs - ツール入力 +- tool_outputs - ツール出力 +- message_data - メッセージデータ +- error - エラー情報（該当する場合） +- inputs - メッセージの入力 +- outputs - メッセージの出力 +- tool_config - ツール設定 +- time_cost - 時間コスト +- tool_parameters - ツールパラメーター +- file_url - 関連するファイルの URL +- メタデータ + - message_id - メッセージ ID + - tool_name - ツール名 + - tool_inputs - ツール入力 + - tool_outputs - ツール出力 + - tool_config - ツール設定 + - time_cost - 時間コスト + - error - エラー情報（該当する場合） + - tool_parameters - ツールパラメーター + - message_file_id - メッセージファイル ID + - created_by_role - 作成者の役割 + - created_user_id - 作成者ユーザーID diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index bfa7881f8..e5b8ef1c0 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,77 +1,619 @@ --- title: Langfuse の統合 -sidebarTitle: Langfuse -description: Dify アプリを Langfuse に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-langfuse) を参照してください。 -## アプリの接続 -Langfuse でプロジェクトを作成し、**Project Settings** > **API Keys** から [API キー](https://langfuse.com/faq/all/where-are-langfuse-api-keys) を取得します。Langfuse Cloud では、利用する [リージョンのベース URL](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url) を選び、末尾の `/api/public` を除きます。セルフホストの場合は、管理者にベース URL を確認してください。 +### Langfuse とは -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Langfuse** の **設定** をクリックし、接続情報を入力してください。 +Langfuse は、チームがアプリケーションのデバッグ、分析、反復作業を協力して行うことができる、オープンソースの大規模言語モデル（LLM）エンジニアリングプラットフォームです。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **秘密キー** | はい | プロジェクトの秘密キー。 | -| **公開キー** | はい | 対応する公開キー。 | -| **Host** | はい | Langfuse インスタンスの HTTP(S) ベース URL。 | + + Langfuse の紹介： [https://langfuse.com/](https://langfuse.com/) + - -この連携では、Langfuse の従来の取り込み API、`/api/public/ingestion` でトレースデータを受信します。`events_only` モードの Langfuse v4 では、このトレースを受信できません。接続前に、Langfuse の管理者と [取り込み API の互換性](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api) を確認してください。 - +### Langfuse の設定方法 -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Langfuse を選ぶと、現在の選択が置き換わります。 +1. [公式ウェブサイト](https://langfuse.com/)で Langfuse に登録し、ログインします。 +2. Langfuse でプロジェクトを作成します。ログイン後、ホームページで **新規** をクリックして自身のプロジェクトを作成します。この **プロジェクト** は、Dify の **アプリケーション** と関連付けてデータを監視するために使用されます。 -保存済みの認証情報は、編集時には表示されません。**Host** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 + + ![Langfuse でプロジェクトを作成します](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) + -## Dify が送信するデータ +プロジェクトの名前を編集してください。 -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 + + ![Langfuse でプロジェクトを作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) + -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 +3. プロジェクト API 資格情報を作成します。プロジェクトの左サイドバーで **設定** をクリックし、設定を開きます。 -Langfuse で生成の記録を開くと、モデル呼び出しで収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 + + ![プロジェクトの API 認証情報を作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) + -### Agent の呼び出しと内容の収集 +設定で **API キーを作成** をクリックして、プロジェクトの API 資格情報を作成します。 - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - + + ![プロジェクトの API 認証情報を作成](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) + + +**シークレットキー**、**パブリックキー**、**ホスト**をコピーして保存します。 + + + ![API キー設定を取得](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) + + +4. Dify で Langfuse を設定します。監視が必要なアプリケーションを開き、サイドメニューで **モニタリング** を開き、ページ上で **アプリパフォーマンスのトレース** を選択します。 + + + ![Langfuse を設定](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) + + +設定をクリックした後、Langfuse で作成した **秘密キー**、**公開キー**、**Host** を入力して保存します。**Host** には、プロジェクトのリージョンまたはセルフホスト環境のベース URL を指定します。`/api/public` は含めないでください。この統合には [レガシー取り込み API](https://langfuse.com/docs/api-and-data-platform/features/public-api) が必要です。`events_only` のインスタンスでは、これらのトレースを受け付けません。 + + + ![Langfuse を設定](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) + + +正常に保存されると、現在のページで状態を確認できます。 -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 + + ![構成ステータスを表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) + -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 +### Langfuse での監視データの閲覧 + +設定後、Dify のアプリケーションのデバッグまたはプロダクションデータを Langfuse で見ることができます。 + + + ![](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) + + + + ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) + -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +### 監視データの一覧 + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 + +#### Workflow と Chatflow の情報をトレースする + +**Workflow と Chatflow のトレース** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ワークフローLangFuse Trace
workflow_run_idid
user_iduserId
workflowname
start\_timetimestamp / startTime
end\_timeendTime（観測）
inputsinput
outputsoutput
モデルトークン消費量（LLM 呼び出し）usage
元データmetadata
errorlevel（観測）
errorstatusMessage（観測）
セッション IDsessionId
親スパン（存在する場合）parentObservationId（入れ子の観測）
+**ワークフロートレース情報** + +* workflow\_id - ワークフローのユニーク ID +* conversation\_id - 会話 ID +* workflow\_run\_id - このランタイムのワークフローID +* tenant\_id - テナント ID +* elapsed\_time - このランタイムの経過時間 +* status - ランタイムのステータス +* version - ワークフローのバージョン +* total\_tokens - このランタイムで使用されたトークンの総数 +* file\_list - 処理されたファイルのリスト +* triggered\_from - このランタイムをトリガーしたソース +* workflow\_run\_inputs - このワークフローの入力 +* workflow\_run\_outputs - このワークフローの出力 +* error - エラーメッセージ +* query - ランタイムで使用されたクエリ +* workflow\_app\_log\_id - Workflow アプリケーションログ ID +* message\_id - 関連するメッセージ ID +* start\_time - このランタイムの開始時間 +* end\_time - このランタイムの終了時間 +* ワークフローノード実行 - ワークフローノードのランタイム情報 +* 元データ（Metadata） + * workflow\_id - ワークフローのユニーク ID + * conversation\_id - 会話 ID + * workflow\_run\_id - このランタイムのワークフローID + * tenant\_id - テナント ID + * elapsed\_time - このランタイムの経過時間 + * status - オペレーション状態 + * version - ワークフローのバージョン + * total\_tokens - このランタイムで使用されたトークンの総数 + * file\_list - 処理されたファイルのリスト + * triggered\_from - このランタイムをトリガーしたソース + +#### メッセージトレース情報 + +**LLM 会話をトレースするために** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
メッセージLangFuse Generation/Trace
message\_idid
end\_user\_session\_iduserId
messagename
start\_timetimestamp / startTime
end\_timeendTime（観測）
inputsinput
outputsoutput
モデルトークン消費量（LLM 呼び出し）usage
元データmetadata
errorlevel（観測）
errorstatusMessage（観測）
セッション IDsessionId
+**メッセージトレース情報** + +* message\_id - メッセージ ID +* message\_data - メッセージデータ +* end\_user\_session\_id - ユーザーのセッション ID +* conversation\_model - 会話モデル +* message\_tokens - メッセージトークン +* answer\_tokens - 回答トークン +* total\_tokens - メッセージと回答からの総トークン +* error - エラーメッセージ +* inputs - 入力データ +* outputs - 出力データ +* file\_list - 処理されたファイルのリスト +* start\_time - 開始時間 +* end\_time - 終了時間 +* conversation\_mode - 会話モード +* 元データ（Metadata） + * conversation\_id - 会話 ID + * ls\_provider - モデルプロバイダー + * ls\_model\_name - モデル ID + * status - メッセージのステータス + * from\_end\_user\_id - 送信ユーザーの ID + * from\_account\_id - 送信アカウントの ID + * agent\_based - エージェントベースかどうか + * workflow\_run\_id - このランタイムのワークフローID + * from\_source - メッセージソース + +#### モデレーショントレース情報 + +**会話のモデレーションを追跡するために使用されます** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
モデレーションLangFuse Generation/Trace
user\_idmetadata.user_id
moderationname
start\_timestartTime
end\_timeendTime（観測）
inputsinput
action, flaggedoutput
元データmetadata
message\_idtraceId
+**メッセージトレース情報** + +* message\_id - メッセージ ID +* user\_id - ユーザーID +* workflow\_app\_log\_id workflow\_app\_log\_id +* inputs - レビューのための入力データ +* message\_data - メッセージデータ +* flagged - 注目のためにフラグが立てられているかどうか +* action - 実施すべき具体的なアクション +* preset\_response - プリセット応答 +* start\_time - レビューの開始時間 +* end\_time - レビューの終了時間 +* 元データ（Metadata） + * message\_id - メッセージ ID + * action - 実施すべき具体的なアクション + * preset\_response - プリセット応答 + +#### 推奨質問のトレース情報 + +**推奨質問を追跡するために使用されます** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
推奨質問LangFuse Generation/Trace
user\_idmetadata.user_id
suggested\_questionname
start\_timestartTime
end\_timeendTime（観測）
inputsinput
suggested_questionoutput
元データmetadata
message\_idtraceId
+**メッセージトレース情報** + +* message\_id - メッセージ ID +* message\_data - メッセージデータ +* inputs - 入力データ +* outputs - 出力データ +* start\_time - 開始時間 +* end\_time - 終了時間 +* total\_tokens - 総トークン数 +* status - メッセージのステータス +* error - エラーメッセージ +* from\_account\_id - 送信アカウント ID +* agent\_based - エージェントベースかどうか +* from\_source - メッセージソース +* model\_provider - モデルプロバイダー +* model\_id - モデル ID +* suggested\_question - 推奨質問 +* level - ステータスレベル +* status\_message - メッセージステータス +* 元データ（Metadata） + * message\_id - メッセージ ID + * ls\_provider - モデルプロバイダー + * ls\_model\_name - モデル ID + * status - メッセージのステータス + * from\_end\_user\_id - 送信ユーザーの ID + * from\_account\_id - 送信アカウント ID + * workflow\_run\_id - このランタイムのワークフローID + * from\_source - メッセージソース + +#### データセットリトリーバルトレース情報 + +**知識ベースの検索を追跡するために使用されます** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
データセットリトリーバルLangFuse Generation/Trace
user\_idmetadata.user_id
dataset\_retrievalname
start\_timestartTime
end\_timeendTime（観測）
inputsinput
documentsoutput
元データmetadata
message\_idtraceId
+**データセットリトリーバルトレース情報** + +* message\_id - メッセージ ID +* inputs - 入力メッセージ +* documents - ドキュメントデータ +* start\_time - 開始時間 +* end\_time - 終了時間 +* message\_data - メッセージデータ +* 元データ（Metadata） + * message\_id - メッセージ ID + * ls\_provider - モデルプロバイダー + * ls\_model\_name - モデル ID + * status - モデルのステータス + * from\_end\_user\_id - 送信ユーザーの ID + * from\_account\_id - 送信アカウントの ID + * agent\_based - エージェントベースかどうか + * workflow\_run\_id - このランタイムのワークフローID + * from\_source - メッセージソース + +#### ツールトレース情報 + +**ツール呼び出しを追跡するために使用されます** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ツールLangFuse Generation/Trace
user\_idmetadata.user_id
tool\_namename
start\_timestartTime
end\_timeendTime（観測）
tool_inputsinput
tool_outputsoutput
元データmetadata
message\_idtraceId
+**ツールトレース情報** + +* message\_id - メッセージ ID +* tool\_name - ツール名 +* start\_time - 開始時間 +* end\_time - 終了時間 +* tool\_inputs - ツール入力 +* tool\_outputs - ツール出力 +* message\_data - メッセージデータ +* error - エラーメッセージが存在する場合 +* inputs - メッセージの入力 +* outputs - メッセージの出力 +* tool\_config - ツール構成 +* time\_cost - 時間コスト +* tool\_parameters - ツールパラメータ +* file\_url - 関連ファイルの URL +* 元データ（Metadata） + * message\_id - メッセージ ID + * tool\_name - ツール名 + * tool\_inputs - ツール入力 + * tool\_outputs - ツール出力 + * tool\_config - ツール構成 + * time\_cost - 時間コスト + * error - エラーメッセージ + * tool\_parameters - ツールパラメータ + * message\_file\_id - メッセージファイル ID + * created\_by\_role - 作成者の役割 + * created\_user\_id - 作成したユーザーID -## 新しいトレースの確認 +#### 名前生成トレース -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**Langfuse** の **見る** をクリックして設定したプロジェクトを開きます。 -3. 実行時刻を手がかりに新しいトレースを探します。開いてモデルの生成やノードのスパンを確認します。 +**会話タイトルの生成を追跡するために使用されます** -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名前生成LangFuse Generation/Trace
user\_idmetadata.user_id
generate\_namename
start\_timestartTime
end\_timeendTime（観測）
inputsinput
outputsoutput
元データmetadata
+**名前生成トレース情報** -## トラブルシューティング +* conversation\_id - 会話 ID +* inputs - 入力データ +* outputs - 生成されたセッション名 +* start\_time - 開始時間 +* end\_time - 終了時間 +* tenant\_id - テナント ID +* 元データ（Metadata） + * conversation\_id - 会話 ID + * tenant\_id - テナント ID - - - 設定の保存時にはプロジェクトへのアクセスを確認します。Langfuse が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、同じプロジェクトを確認します。 +### Langfuse プロンプト管理 - 管理者に、ワーカーログの取り込みエラーを調べてもらってください。Langfuse が `/api/public/ingestion` 経由でデータを受信できることも確認します。新しい実行がまだ表示されない場合は、[トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) も確認してもらってください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 +[Langfuse プロンプト管理プラグイン](https://github.com/gao-ai-com/dify-plugin-langfuse)（コミュニティによって維持されている）は、Dify アプリケーションで[Langfuse で管理およびバージョン管理されているプロンプト](https://langfuse.com/docs/prompt-management/get-started)を使用できるようにし、大規模言語モデル（LLM）アプリケーション開発のワークフローを向上させます。主な機能は以下の通りです： - プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - +- **プロンプトを取得する**：Langfuse で管理されている特定のプロンプトを取得します。 +- **プロンプトを検索する**：Langfuse でさまざまなフィルターを使用してプロンプトを検索します。 +- **プロンプトを更新する**：Langfuse でプロンプトの新しいバージョンを作成し、タグ/ラベルを設定します。 -Langfuse で管理するプロンプトを利用するには、[Langfuse Prompt Management Plugin](https://github.com/gao-ai-com/dify-plugin-langfuse) を参照してください。コミュニティが保守するプラグインで、リンク先にインストール方法と使い方があります。 +この統合により、プロンプトの管理およびバージョン管理のプロセスが合理化され、より効率的な開発と反復サイクルに寄与します。プラグインとインストール手順は[こちら](https://github.com/gao-ai-com/dify-plugin-langfuse)で見つけることができます。 diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index 2d300c4b4..4d62dac17 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,73 +1,361 @@ --- title: LangSmith の統合 -sidebarTitle: LangSmith -description: Dify アプリを LangSmith に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-langsmith) を参照してください。 -## アプリの接続 -対象のワークスペースでプロジェクトを読み取り、トレースを送信できる [LangSmith API キー](https://docs.langchain.com/langsmith/create-account-api-key) を取得します。使用するプロジェクト名を決めておきます。 +### 1 LangSmith とは -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**LangSmith** の **設定** をクリックし、接続情報を入力してください。 +LangSmith は LLM アプリケーションの開発、コラボレーション、テスト、デプロイ、監視などのツールを提供するプラットフォームです。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **API Key** | はい | プロジェクトの読み取りとトレースの書き込み権限を持つキー。 | -| **プロジェクト** | はい | プロジェクト名。存在しない場合、最初のトレースの受信時に LangSmith が作成します。 | -| **Endpoint** | いいえ | 既定値は `https://api.smith.langchain.com`。独自の API エンドポイントには HTTPS が必須です。必要なパスプレフィックスも含めてください。 | + +LangSmith の公式サイト：[https://www.langchain.com/langsmith](https://www.langchain.com/langsmith) + -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。LangSmith を選ぶと、現在の選択が置き換わります。 +### 2 LangSmith の使い方 -保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 +#### 1. LangSmith の[公式サイト](https://www.langchain.com/langsmith)から登録し、ログインする。 -## Dify が送信するデータ +#### 2. LangSmith からプロジェクトを作成します -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +ログイン後、ホームページの **New Project** をクリックし、新たな **プロジェクト**を作成します。このプロジェクトは、Dify 内の **アプリ**と連動したデータモニタリングに使用されます。 -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 + + ![新たなプロジェクトを作成します。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) + -LangSmith でモデルの実行を開くと、収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 +作成する後、プロジェクトの中にチェクできます。 -### Agent の呼び出しと内容の収集 + + ![LangSmith の中にプロジェクトをチェクします。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) + - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - +#### 3. プロジェクト認証情報の作成 + +左のサイドバーでプロジェクト **設定** を見つける。 + + + ![プロジェクトを設定し](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) + + +**Create API Key** をクリックし，新たな認証情報を作ります。 + + + ![プロジェクトの API Key を作ります。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) + + +**Personal Access Token** を選び，のちほとの API 身分証明の時使えます。 + + + ![Personal Access Token を選択します](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) + + +新たな API key をコピーし、保存します。 + + + ![新たな API key をコピーします](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) + + +#### 4. Dify アプリの中に LangSmith を設定します + +監視用のアプリのサイトメニューの **監視** ボタンをクリックし，**設定** をクリックします。 + + + ![LangSmith を設定します](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/b6c7e5d4c2ca2092d59465cca27bc69c.png) + + +設定をクリックしたら、**API Key** と **プロジェクト** 名を入力して保存します。キーにはプロジェクトの読み取り権限とトレースの書き込み権限が必要です。**Endpoint** のデフォルトは `https://api.smith.langchain.com` です。カスタム API エンドポイントには HTTPS を使用してください。 + + + ![ LangSmith を設定します。](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/93dfabcadb7b2ff597f54beb5e642124.png) + + + +設定したプロジェクト名は LangSmith のいるプロジェクト名と必ず一致します。プロジェクトが存在しない場合、LangSmith は最初のトレースが到着した時点で作成します。設定の保存時には作成されません。 + -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +保存に成功すると、現在のページで監視状態を見ることができます。 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 + + ![監視状態を見る](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/43369dc4de8f606c166fae2efab97d73.png) + + +### LangSmith でのモニタリングデータの表示 + +Dify 内のアプリケーションからデバッグや製品データを設定することで、LangSmith にてそのデータをモニタリングすることができます。 + + + ![Dify におけるアプリケーションのデバッグ](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/a1370fdbb79257cba31a565ac6764802.png) + + +LangSmith に切り替えると、ダッシュボード上で Dify アプリケーションの詳細な操作ログを見ることができます。 + + + ![LangSmith でのアプリケーションデータの表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) + + +LangSmith を通じて得られる詳細な大規模言語モデル（LLM）の操作ログは、Dify アプリケーションのパフォーマンスを最適化するために役立ちます。 + + + ![LangSmith でのアプリケーションデータの表示](https://assets-docs.dify.ai/dify-enterprise-mintlify/jp/guides/monitoring/integrate-external-ops-tools/beeb4ee50c80de8db7400c1f65727c8c.png) + -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +### モニタリングデータリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 + +#### Workflow/Chatflow のトレース情報 + +Workflow や Chatflow を追跡するために使用されます。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ワークフローLangSmith Chain
workflow_run_idid
user_idextra.metadata.user_id
workflowname
start\_time開始時間
end\_time終了時間
inputs入力
outputs出力
モデルトークン消費量（LLM 呼び出し）outputs.usage_metadata
metadataextra.metadata
エラーエラー
セッション IDextra.metadata.session_id
親スパン（存在する場合）parent_run_id
+**ワークフロートレース情報** + +- workflow\_id：ワークフローの固有識別子 +- conversation\_id：会話 ID +- workflow\_run\_id：現在の実行 ID +- tenant\_id：テナント ID +- elapsed\_time：現在の実行にかかった時間 +- status：実行ステータス +- version：ワークフローのバージョン +- total\_tokens：現在の実行で使用されるトークンの合計数 +- file\_list：処理されたファイルのリスト +- triggered\_from：現在の実行を引き起こしたソース +- workflow\_run\_inputs：現在の実行の入力データ +- workflow\_run\_outputs：現在の実行の出力データ +- error：現在の実行中に発生したエラー +- query：実行中に使用されたクエリ +- workflow\_app\_log\_id：Workflow アプリケーションログ ID +- message\_id：関連メッセージ ID +- start\_time：実行の開始時間 +- end\_time：実行の終了時間 +- workflow node executions：ワークフローノード実行に関する情報 +- メタデータ + - workflow\_id：ワークフローの固有識別子 + - conversation\_id：会話 ID + - workflow\_run\_id：現在の実行 ID + - tenant\_id：テナント ID + - elapsed\_time：現在の実行にかかった時間 + - status：実行ステータス + - version：ワークフローのバージョン + - total\_tokens：現在の実行で使用されるトークンの合計数 + - file\_list：処理されたファイルのリスト + - triggered\_from：現在の実行を引き起こしたソース + +#### メッセージトレース情報 + +大規模言語モデル（LLM）関連の会話を追跡するために使用されます。 -## 新しいトレースの確認 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
チャットLangSmith Chain / LLM
message\_idid
end\_user\_session\_idextra.metadata.end_user_session_id
messagename
start\_time開始時間
end\_time終了時間
inputs入力
outputs出力
モデルトークン消費量（LLM 呼び出し）outputs.usage_metadata
metadataextra.metadata
エラーエラー
セッション IDextra.metadata.session_id
+**メッセージトレース情報** -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**LangSmith** の **見る** をクリックします。 -3. 設定したプロジェクトで、実行時刻を手がかりに新しい実行を探し、子の実行を確認します。 +- message\_id：メッセージ ID +- message\_data：メッセージデータ +- end\_user\_session\_id：ユーザーセッション ID +- conversation\_model：会話モード +- message\_tokens：メッセージ中のトークン数 +- answer\_tokens：回答のトークン数 +- total\_tokens：メッセージと回答の合計トークン数 +- error：エラー情報 +- inputs：入力データ +- outputs：出力データ +- file\_list：処理されたファイルのリスト +- start\_time：開始時間 +- end\_time：終了時間 +- conversation\_mode：会話モード +- メタデータ + - conversation\_id：会話 ID + - ls\_provider：モデルプロバイダ + - ls\_model\_name：モデル ID + - status：メッセージステータス + - from\_end\_user\_id：送信ユーザーの ID + - from\_account\_id：送信アカウントの ID + - agent\_based：メッセージがエージェントベースかどうか + - workflow\_run\_id：ワークフロー実行 ID + - from\_source：メッセージのソース -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +#### モデレーショントレース情報 -最初のトレースを受信した後も **見る** でプロジェクト一覧が開く場合は、設定を再度保存してプロジェクトのリンクを更新してください。 +会話のモデレーションを追跡するために使用されます。 -## トラブルシューティング + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
モデレーションLangSmith Tool
user\_idextra.metadata.user_id
moderationname
start\_time開始時間
end\_time終了時間
inputs入力
action, flagged出力
metadataextra.metadata
message\_id親実行 ID
+**モデレーショントレース情報** - - - 保存時にはプロジェクトへのアクセスを確認します。新しいプロジェクトは、最初のトレースの受信時に作成されます。LangSmith が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、設定した名前と一致するプロジェクトを確認します。 +- message\_id：メッセージ ID +- user\_id：ユーザーID +- workflow\_app\_log\_id：Workflow アプリケーションログ ID +- inputs：モデレーションの入力データ +- message\_data：メッセージデータ +- flagged：コンテンツに注意が必要かどうか +- action：実行された具体的なアクション +- preset\_response：プリセット応答 +- start\_time：モデレーション開始時間 +- end\_time：モデレーション終了時間 +- メタデータ + - message\_id：メッセージ ID + - action：実行された具体的なアクション + - preset\_response：プリセット応答 - 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 +#### 提案された質問トレース情報 - プライベートネットワークのエンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - +提案された質問を追跡するために使用されます。 diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx index 20ca78fc0..e5c600795 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,72 +1,524 @@ --- title: Opik の統合 -sidebarTitle: Opik -description: Dify アプリを Opik に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-opik) を参照してください。 -## アプリの接続 -ホスト型 Opik の API キーを取得するか、独自の Opik インスタンスを使用します。アカウントの準備については、[Opik の Dify 連携ガイド](https://www.comet.com/docs/opik/integrations/dify) を参照してください。独自のサーバー上の特定のワークスペースを使う場合は、その名前を管理者に確認します。 +## Opik の概要 -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。Opik の項目（**オピック**）で **設定** をクリックし、接続情報を入力してください。 +Opik は、大規模言語モデル（LLM）アプリケーションを評価、テスト、および監視するためのオープンソースプラットフォームです。LLM ベースのアプリケーション開発において、直感的な評価・テスト・監視機能を提供し、開発効率の向上を支援します。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **API Key** | ホスト型 Opik では必須 | アカウントの API キー。認証を使用しないサーバーに限り、空欄にできます。 | -| **プロジェクト** | いいえ | プロジェクト名。最初のトレースの受信時に Opik が作成します。空欄の場合、Dify は `Default Project` を使用します。 | -| **Workspace** | いいえ | 既存のワークスペース。空欄の場合、Dify はアカウントの既定のワークスペースを使用します。認証なしのオープンソース版サーバーでは `default` を使用します。 | -| **Url** | いいえ | 既定値は `https://www.comet.com/opik/api/`。独自の HTTP(S) URL は末尾を `/api/` にしてください。 | + +詳細については、[Opik](https://www.comet.com/site/products/opik/) をご参照ください。 + -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Opik を選ぶと、現在の選択が置き換わります。 +--- -保存済みの認証情報は、編集時には表示されません。**Url** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 +## Opik の導入ガイド -## Dify が送信するデータ +ホスト型 Opik では、以下のアカウントと API キーの手順に従ってください。認証を使用しないセルフホスト環境では、**API Key** を空欄にできます。 -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +### 1. [Opik](https://www.comet.com/signup?from=llm) に登録/ログイン -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 +### 2. Opik API キーの取得 -Opik で LLM スパンを開くと、モデル呼び出しで収集した入出力を確認できます。token 数や USD 建ての費用を取得できる場合は、使用量と費用のフィールドに表示されます。 +右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 -### Agent の呼び出しと内容の収集 + + ![Opik API キー](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) + - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - +### 3. Opik と Dify を統合 + +Dify アプリケーションで Opik を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 + + + ![アプリケーションパフォーマンスを追跡](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) + + +設定をクリックした後、必要に応じて **API Key** と **プロジェクト** 名を入力します。プロジェクト名が空欄の場合は `Default Project` が使われ、新しいプロジェクトは最初のトレースで作成されます。**Workspace** を空欄にすると、アカウントのデフォルトワークスペースが使われます。セルフホストの Opik では、**Url** に `/api/` で終わる API ベース URL を指定して保存します。デフォルトは `https://www.comet.com/opik/api/` です。 + + + ![Opik の設定](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) + + +保存に成功すると、現在のページで監視ステータスを確認できます。 + +## 監視データの確認 + +設定が完了すると、Dify アプリケーションを通常通りデバッグまたは使用できます。新しい実行を Opik で監視できます。過去の使用履歴はさかのぼって送信されません。 + + + ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) + -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +Opik に切り替えると、ダッシュボードで Dify アプリケーションの詳細な操作ログを確認できます。 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 + + ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) + + +Opik の詳細な LLM 操作ログにより、Dify アプリケーションのパフォーマンスを最適化できます。 + + + ![Opik でアプリデータを確認](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) + -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +## モニタリングデータリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 -## 新しいトレースの確認 +### **ワークフロー/会話フロートラッキング情報** + +**ワークフローと会話フローの追跡に使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ワークフローOpik トラッキング
workflow_run_idid
user_idmetadata.user_id
workflowname
start_timestart_time
end_timeend_time
inputsinput
outputsoutput
モデルトークン消費量（LLM 呼び出し）usage
metadatametadata
errorerror_info
セッション IDthread_id（トレース）
+**ワークフロートラッキング情報** + +- workflow_id - ワークフローの一意識別子 +- conversation_id - 会話 ID +- workflow_run_id - 現在の実行 ID +- tenant_id - テナント ID +- elapsed_time - 現在の実行にかかった時間 +- status - 実行ステータス +- version - ワークフローバージョン +- total_tokens - 現在の実行で使用されたトークン総数 +- file_list - 処理されたファイルのリスト +- triggered_from - 実行をトリガーしたソース +- workflow_run_inputs - 現在の実行の入力データ +- workflow_run_outputs - 現在の実行の出力データ +- error - 実行中に発生したエラー +- query - 実行中に使用されたクエリ +- workflow_app_log_id - Workflow アプリケーションログ ID +- message_id - 関連するメッセージ ID +- start_time - 実行開始時間 +- end_time - 実行終了時間 +- workflow node executions - ワークフローノードの実行情報 +- メタデータ + - workflow_id - ワークフローの一意識別子 + - conversation_id - 会話 ID + - workflow_run_id - 現在の実行 ID + - tenant_id - テナント ID + - elapsed_time - 現在の実行にかかった時間 + - status - 実行ステータス + - version - ワークフローバージョン + - total_tokens - 現在の実行で使用されたトークン総数 + - file_list - 処理されたファイルのリスト + - triggered_from - 実行をトリガーしたソース + +--- -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**オピック** の **見る** をクリックします。コンソールが開いた場合は、設定したワークスペースとプロジェクトを選択します。 -3. 実行時刻を手がかりに新しいトレースを探し、開いてスパンを確認します。 +### **メッセージトラッキング情報** -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +**LLM 関連の会話を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
チャットOpik Trace
message_idid
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time
end_timeend_time
inputsinput
outputsoutput
モデルトークン消費量（LLM 呼び出し）usage
metadatametadata
セッション IDthread_id（トレース）
+**メッセージトラッキング情報** + +- message_id - メッセージ ID +- message_data - メッセージデータ +- end_user_session_id - ユーザーセッション ID +- conversation_model - 会話モード +- message_tokens - メッセージ内のトークン数 +- answer_tokens - 回答内のトークン数 +- total_tokens - メッセージと回答のトークン総数 +- error - エラー情報 +- inputs - 入力データ +- outputs - 出力データ +- file_list - 処理されたファイルリスト +- start_time - 開始時間 +- end_time - 終了時間 +- conversation_mode - 会話モード +- メタデータ + - conversation_id - 会話 ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージソース + +### **レビュー追跡情報** + +**会話のレビューを追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
レビューOpik Tool
user_idmetadata.user_id
"moderation"name
start_timestart_time
end_timeend_time
inputsinput
action, flaggedoutput
metadatametadata
+**レビュー追跡情報** + +- message_id - メッセージ ID +- user_id - ユーザーID +- workflow_app_log_id - Workflow アプリケーションログ ID +- inputs - レビュー入力データ +- message_data - メッセージデータ +- flagged - 注意が必要とマークされたかどうか +- action - 実施された具体的なアクション +- preset_response - プリセットレスポンス +- start_time - レビュー開始時間 +- end_time - レビュー終了時間 +- メタデータ + - message_id - メッセージ ID + - action - 実施されたアクション + - preset_response - プリセットレスポンス + +--- + +### **提案質問追跡情報** + +**提案質問を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
提案質問Opik Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time
end_timeend_time
inputsinput
suggested_questionoutput
metadatametadata
+**提案質問追跡情報** + +- message_id - メッセージ ID +- message_data - メッセージデータ +- inputs - 入力データ +- outputs - 出力データ +- start_time - 開始時間 +- end_time - 終了時間 +- total_tokens - トークン総数 +- status - メッセージステータス +- error - エラー情報 +- from_account_id - 送信アカウント ID +- agent_based - エージェントベースかどうか +- from_source - メッセージの送信元 +- model_provider - モデルプロバイダー +- model_id - モデル ID +- suggested_question - 提案された質問 +- level - ステータスレベル +- status_message - ステータスメッセージ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- + +### **データセット検索追跡情報** + +**ナレッジベース検索を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
データセット検索Opik Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time
end_timeend_time
inputsinput
documentsoutput
metadatametadata
message_idtrace_id
+**データセット検索追跡情報** + +- message_id - メッセージ ID +- inputs - 入力データ +- documents - ドキュメントデータ +- start_time - 開始時間 +- end_time - 終了時間 +- message_data - メッセージデータ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- -## トラブルシューティング +### **ツール追跡情報** - - - 保存時にはワークスペースへのアクセスを確認します。プロジェクトは、最初のトレースの受信時に Opik が作成します。Opik が選択され、トレースが有効になっていることを確認してください。Opik で、Dify に設定したワークスペースとプロジェクトを開き、アプリを再度実行します。 +**ツールの呼び出しを追跡するために使用** - 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ツールOpik Tool
user_idmetadata.user_id
tool_namename
start_timestart_time
end_timeend_time
tool_inputsinput
tool_outputsoutput
metadatametadata
+**ツール追跡情報** - プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - +- message_id - メッセージ ID +- tool_name - ツール名 +- start_time - 開始時間 +- end_time - 終了時間 +- tool_inputs - ツール入力 +- tool_outputs - ツール出力 +- message_data - メッセージデータ +- error - エラー情報（該当する場合） +- inputs - メッセージの入力 +- outputs - メッセージの出力 +- tool_config - ツール設定 +- time_cost - 時間コスト +- tool_parameters - ツールパラメーター +- file_url - 関連するファイルの URL +- メタデータ + - message_id - メッセージ ID + - tool_name - ツール名 + - tool_inputs - ツール入力 + - tool_outputs - ツール出力 + - tool_config - ツール設定 + - time_cost - 時間コスト + - error - エラー情報（該当する場合） + - tool_parameters - ツールパラメーター + - message_file_id - メッセージファイル ID + - created_by_role - 作成者の役割 + - created_user_id - 作成者ユーザーID diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index 9f8e0b460..e43a81ffa 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,75 +1,554 @@ --- title: Phoenix の統合 -sidebarTitle: Phoenix -description: Dify アプリを Phoenix に接続し、新しいトレースを確認して、送信する Agent データを選択します --- > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-phoenix) を参照してください。 -## アプリの接続 -Dify の各サービスから接続できる Phoenix インスタンスを使用します。セルフホストでも Phoenix Cloud でも利用できます。認証が必要な場合は、プロジェクトの読み取りとトレースの送信ができる [API キー](https://arize.com/docs/phoenix/settings/api-keys) を取得します。Arize に接続する場合は、[Arize 連携](/ja/self-host/use-dify/monitor/integrations/integrate-arize) の手順に従ってください。 +### 1 Phoenix とは -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。**Phoenix** の **設定** をクリックし、接続情報を入力してください。 +[Arize Phoenix](https://arize.com/phoenix/) は、[Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) が提供するオープンソースのプラットフォームです。OpenTelemetry をベースに、LLM ワークフローとエージェントの可観測性、評価、プロンプトエンジニアリング、実験に対応します。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **API Key** | 認証が有効な場合 | インスタンスまたは Phoenix Cloud スペースのキー。認証なしのサーバーでは空欄にします。 | -| **プロジェクト** | はい | 送信先のプロジェクト名。 | -| **Endpoint** | いいえ | Phoenix のベース URL。既定値の `https://app.phoenix.arize.com` を、Cloud スペースまたはセルフホストのインスタンスの URL に置き換えます。パスプレフィックスも含めてください。 | +開発中は Phoenix をローカルで実行できます。自社インフラに単一コンテナとしてセルフホストするか、Arize がホストする [Phoenix Cloud](#3-phoenix-cloud-の使い方) を利用することもできます。 -Phoenix Cloud では、`https://app.phoenix.arize.com/s/` など、スペースのホスト名をコピーします。取得場所は [Phoenix エンドポイントの確認方法](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint) を参照してください。ベース URL に `/v1/traces` は含めません。このパスは Dify が追加します。 +本番運用チームや AI ネイティブ企業、エンタープライズにはフル機能の [Arize AX](https://arize.com/products/ax/) が適しています。必要な場合は、代わりに [Arize 統合](/ja/self-host/use-dify/monitor/integrations/integrate-arize) を設定してください。 -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Phoenix を選ぶと、現在の選択が置き換わります。 +トレースの送信が始まったら、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。障害のデバッグ、エージェント動作の評価、モデル品質のモニタリングにトレースを活用する方法を確認できます。 -保存済みの認証情報は、編集時には表示されません。**Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。送信先を変更した場合は、認証情報を再入力してください。 +### 2 Phoenix の使い方 -## Dify が送信するデータ +認証を使用しないセルフホストの Phoenix では、以下のアカウントと API キーの手順を省略できます。**API Key** は空欄にしてください。 -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +#### 1. Phoenix の[公式サイト](https://app.arize.com/auth/phoenix/signup)から登録し、ログインする。 -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 +### 2. Phoenix API キーの取得 -Phoenix でモデルのスパンを開くと、収集した入出力や取得できた token 数を確認できます。Dify は Phoenix に標準で用意されている費用フィールドには値を設定しません。 +右上のユーザーメニューから **API Key** を選択し、API キーを取得・コピーしてください。 -### Agent の呼び出しと内容の収集 + + ![Phoenix API キー](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) + - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - +### 3. Phoenix と Dify を統合 + +Dify アプリケーションで Phoenix を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 + + + ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +設定をクリックした後、**プロジェクト** 名と、認証が有効な場合は **API Key** を入力します。**Endpoint** には Phoenix インスタンスのベース URL を指定して保存します。取り込みパスは Dify が追加するため、`/v1/traces` は付けないでください。 + + + ![Phoenix の設定](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + + +保存に成功すると、現在のページで監視ステータスを確認できます。 + + + ![Phoenix の設定](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + + +### 3 Phoenix Cloud の使い方 + +#### 1. Phoenix Cloud の[公式サイト](https://app.arize.com/auth/phoenix/signup)から登録し、ログインする。 + +### 2. Phoenix スペースの作成 + +右上のユーザーメニューから Phoenix スペースを作成できます。スペースを作成 をクリックし、スペース用の一意の URL 識別子を入力してください。 + + + ![Phoenix Cloud で Space を作成](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) + -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +保存に成功すると、概要ページでスペースのステータスを確認できます。 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 + + ![Phoenix Cloud Space の概要](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) + + +### 3. Phoenix API キーの作成 + +スペースを起動した後、左下のユーザーメニューから 設定 を開き、Phoenix API キーを作成できます。システムキー をクリックし、API キーの名前を入力してください。 + + + ![Phoenix Cloud API キー](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) + + +### 4. Phoenix Cloud と Dify を統合 + +Dify アプリケーションで Phoenix を設定します。監視するアプリケーションを開き、サイドメニューで **監視** を選択し、ページ上の **アプリケーションパフォーマンスを追跡** をクリックします。 + + + ![アプリケーションパフォーマンスを追跡](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +設定画面で **API Key** と **プロジェクト** 名を入力します。**Endpoint** には Phoenix Cloud スペースの完全な URL（例：`https://app.phoenix.arize.com/s/`）を指定して保存してください。 + + + ![Phoenix の設定](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + + +保存に成功すると、現在のページで監視ステータスを確認できます。 + + + ![Phoenix の設定](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +## モニタリングデータリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 -## 新しいトレースの確認 +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**Phoenix** の **見る** をクリックして設定したプロジェクトを開きます。 -3. 実行時刻を手がかりに新しいトレースを探し、開いて子のスパンを確認します。 +### **ワークフロー/会話フロートラッキング情報** -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +**ワークフローと会話フローの追跡に使用** -## トラブルシューティング + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ワークフローPhoenix トラッキング
workflow_run_idspan_id
user_idmetadata.user_id
workflowname
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
モデルトークン消費量（LLM 呼び出し）llm.token_count.prompt / completion / total
metadatametadata
errorstatus.code / status.message
セッション IDsession.id
+**ワークフロートラッキング情報** + +- workflow_id - ワークフローの一意識別子 +- conversation_id - 会話 ID +- workflow_run_id - 現在の実行 ID +- tenant_id - テナント ID +- elapsed_time - 現在の実行にかかった時間 +- status - 実行ステータス +- version - ワークフローバージョン +- total_tokens - 現在の実行で使用されたトークン総数 +- file_list - 処理されたファイルのリスト +- triggered_from - 実行をトリガーしたソース +- workflow_run_inputs - 現在の実行の入力データ +- workflow_run_outputs - 現在の実行の出力データ +- error - 実行中に発生したエラー +- query - 実行中に使用されたクエリ +- workflow_app_log_id - Workflow アプリケーションログ ID +- message_id - 関連するメッセージ ID +- start_time - 実行開始時間 +- end_time - 実行終了時間 +- workflow node executions - ワークフローノードの実行情報 +- メタデータ + - workflow_id - ワークフローの一意識別子 + - conversation_id - 会話 ID + - workflow_run_id - 現在の実行 ID + - tenant_id - テナント ID + - elapsed_time - 現在の実行にかかった時間 + - status - 実行ステータス + - version - ワークフローバージョン + - total_tokens - 現在の実行で使用されたトークン総数 + - file_list - 処理されたファイルのリスト + - triggered_from - 実行をトリガーしたソース + +--- + +### **メッセージトラッキング情報** + +**LLM 関連の会話を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
チャットPhoenix Trace
message_idspan_id
end_user_session_idmetadata.end_user_session_id
messagename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
outputsoutput.value
モデルトークン消費量（LLM 呼び出し）llm.token_count.prompt / completion / total
metadatametadata
セッション IDsession.id
+**メッセージトラッキング情報** + +- message_id - メッセージ ID +- message_data - メッセージデータ +- end_user_session_id - ユーザーセッション ID +- conversation_model - 会話モード +- message_tokens - メッセージ内のトークン数 +- answer_tokens - 回答内のトークン数 +- total_tokens - メッセージと回答のトークン総数 +- error - エラー情報 +- inputs - 入力データ +- outputs - 出力データ +- file_list - 処理されたファイルリスト +- start_time - 開始時間 +- end_time - 終了時間 +- conversation_mode - 会話モード +- メタデータ + - conversation_id - 会話 ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージソース + +### **レビュー追跡情報** + +**会話のレビューを追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
レビューPhoenix Tool
user_idmetadata.user_id
"moderation"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
action, flaggedoutput.value
metadatametadata
+**レビュー追跡情報** + +- message_id - メッセージ ID +- user_id - ユーザーID +- workflow_app_log_id - Workflow アプリケーションログ ID +- inputs - レビュー入力データ +- message_data - メッセージデータ +- flagged - 注意が必要とマークされたかどうか +- action - 実施された具体的なアクション +- preset_response - プリセットレスポンス +- start_time - レビュー開始時間 +- end_time - レビュー終了時間 +- メタデータ + - message_id - メッセージ ID + - action - 実施されたアクション + - preset_response - プリセットレスポンス + +--- + +### **提案質問追跡情報** + +**提案質問を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
提案質問Phoenix Trace
user_idmetadata.user_id
"suggested_question"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
suggested_questionoutput.value
metadatametadata
+**提案質問追跡情報** + +- message_id - メッセージ ID +- message_data - メッセージデータ +- inputs - 入力データ +- outputs - 出力データ +- start_time - 開始時間 +- end_time - 終了時間 +- total_tokens - トークン総数 +- status - メッセージステータス +- error - エラー情報 +- from_account_id - 送信アカウント ID +- agent_based - エージェントベースかどうか +- from_source - メッセージの送信元 +- model_provider - モデルプロバイダー +- model_id - モデル ID +- suggested_question - 提案された質問 +- level - ステータスレベル +- status_message - ステータスメッセージ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- + +### **データセット検索追跡情報** + +**ナレッジベース検索を追跡するために使用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
データセット検索Phoenix Retriever
user_idmetadata.user_id
"dataset_retrieval"name
start_timestart_time_unix_nano
end_timeend_time_unix_nano
inputsinput.value
documentsoutput.value
metadatametadata
message_idparent_span_id
+**データセット検索追跡情報** + +- message_id - メッセージ ID +- inputs - 入力データ +- documents - ドキュメントデータ +- start_time - 開始時間 +- end_time - 終了時間 +- message_data - メッセージデータ +- メタデータ + - message_id - メッセージ ID + - ls_provider - モデルプロバイダー + - ls_model_name - モデル ID + - status - メッセージステータス + - from_end_user_id - 送信ユーザーID + - from_account_id - 送信アカウント ID + - agent_based - エージェントベースかどうか + - workflow_run_id - ワークフロー実行 ID + - from_source - メッセージの送信元 + +--- - - - 保存時にはプロジェクトの読み取り権限を確認します。トレースは送信しません。Phoenix が選択され、トレースが有効になっていることを確認してください。アプリを再度実行し、設定したプロジェクトを確認します。 +### **ツール追跡情報** - 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 +**ツールの呼び出しを追跡するために使用** - プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ツールPhoenix Tool
user_idmetadata.user_id
tool_namename
start_timestart_time_unix_nano
end_timeend_time_unix_nano
tool_inputsinput.value
tool_outputsoutput.value
metadatametadata
+**ツール追跡情報** -収集したトレースの評価方法については、Arize の [エージェント評価ガイド](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) と [LLM 評価ガイド](https://arize.com/resources/llm-evaluation/) を参照してください。 +- message_id - メッセージ ID +- tool_name - ツール名 +- start_time - 開始時間 +- end_time - 終了時間 +- tool_inputs - ツール入力 +- tool_outputs - ツール出力 +- message_data - メッセージデータ +- error - エラー情報（該当する場合） +- inputs - メッセージの入力 +- outputs - メッセージの出力 +- tool_config - ツール設定 +- time_cost - 時間コスト +- tool_parameters - ツールパラメーター +- file_url - 関連するファイルの URL +- メタデータ + - message_id - メッセージ ID + - tool_name - ツール名 + - tool_inputs - ツール入力 + - tool_outputs - ツール出力 + - tool_config - ツール設定 + - time_cost - 時間コスト + - error - エラー情報（該当する場合） + - tool_parameters - ツールパラメーター + - message_file_id - メッセージファイル ID + - created_by_role - 作成者の役割 + - created_user_id - 作成者ユーザーID diff --git a/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx index 2de4403e3..2602dff8c 100644 --- a/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/ja/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -6,70 +6,347 @@ description: Dify アプリケーションからトレースを W&B Weave に送 > このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/monitor/integrations/integrate-weave) を参照してください。 -## アプリの接続 + + Dify v1.3.1 以上が必要です。 + -Dify を設定する前に、[API キー](https://wandb.ai/authorize) で書き込める [W&B プロジェクト](https://docs.wandb.ai/models/track/project-page#create-a-project) を作成します。チームのプロジェクトでは、そのチームを **Entity** に指定します。 +### W&B Weave とは -Dify アプリで **監視**（Agent アプリでは **モニタリング**）> **アプリのパフォーマンスの追跡** を開きます。Weave の項目（**織る**）で **設定** をクリックし、接続情報を入力してください。 +Weights & Biases (W&B) Weave は、LLM ベースのアプリケーションの追跡、実験、評価、デプロイ、改善のためのフレームワークです。柔軟性とスケーラビリティを考慮して設計された Weave は、LLM アプリケーション開発ワークフローのあらゆる段階をサポートします。 -| フィールド | 必須 | 値 | -|:------|:---------|:------| -| **API Key** | はい | W&B の API キー。 | -| **プロジェクト** | はい | 書き込み可能な既存のプロジェクト。ここに `entity/project` を入力して、**Entity** を空欄にしてもかまいません。 | -| **Entity** | いいえ | W&B のチームまたはユーザー。空欄の場合、Dify は API キーの既定のエンティティを取得します。 | -| **Endpoint** | いいえ | Weave のトレースサーバー。既定値は `https://trace.wandb.ai`。HTTPS が必須です。 | -| **Host** | いいえ | W&B の API サーバー。既定値は `https://api.wandb.ai`。HTTP(S) を使用できます。 | + + 詳細については、[Weave](https://docs.wandb.ai/weave) を参照してください。 + -独自のデプロイ先を使う場合は、トレースサーバーの **Endpoint** と W&B API の **Host** を管理者に確認します。指定されたパスプレフィックスも含めてください。 +### Weave の設定方法 -[Dify が送信するデータ](#dify-が送信するデータ) を確認してから、**保存 & 有効に** をクリックします。各アプリで有効にできるトレースプロバイダーは 1 つです。Weave を選ぶと、現在の選択が置き換わります。 +#### 1. [W&B Weave](https://wandb.ai/signup)に登録/ログイン -保存済みの認証情報は、編集時には表示されません。**Host** と **Endpoint** を変更しない場合、空欄のままにすると保存済みの値を維持できます。どちらかのアドレスを変更した場合は、認証情報を再入力してください。 +API キーを取得する -## Dify が送信するデータ +次に、https://wandb.ai で Weights & Biases (W&B) アカウントを作成し、https://wandb.ai/authorize から API キーをコピーします -トレースには、アプリの 1 回の実行が **スパン** と呼ばれる処理単位で記録されます。各スパンには実行時間やステータス、エラーが含まれます。Dify は収集した入出力やモデルの使用量も送信します。メッセージ、ワークフロー、ノードの ID など、識別用のメタデータも含まれます。 +#### 2. W&B Weave を Dify と統合する -Workflow アプリでは、ループやイテレーションのグループを含むノードのスパンを確認できます。チャットのトレースでは、メッセージの下にモデル呼び出しが表示されます。Chatflow アプリのトレースでは、メッセージの下にワークフローが表示されます。 +Dify アプリケーションで Weave を設定します。監視が必要なアプリケーションを開き、サイドメニューの **モニタリング** を開き、ページ上の **アプリケーションパフォーマンスの追跡** を選択します。 -Weave でモデル呼び出しを開くと、収集した入出力を確認できます。取得できた token 数は、呼び出しのモデル別使用量に表示されます。Dify は Weave に標準で用意されている費用フィールドには値を設定しません。 + + ![Dify アプリケーションで Weave を設定します](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) + -### Agent の呼び出しと内容の収集 +設定をクリックした後、**API Key** と、既存の書き込み可能な **プロジェクト** 名を入力します。**Entity** は任意です。空欄の場合は API キーのデフォルトエンティティが使われ、チームの場合もあります。入力後、設定を保存します。 - -Agent アプリと [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) のトレースは、既定では無効です。デプロイ先の管理者に、`OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を設定するよう依頼してください。設定場所は [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。 - + + ![](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) + + +正常に保存されると、現在のページで監視状態を確認できます。 + + + ![](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) + + +### Weave でモニタリングデータを表示する -アプリのトレース設定にある **Agent データ収集** で、次の項目を設定します。 +設定が完了すると、Dify 内のアプリケーションからのデバッグまたは本番データを Weave で監視できます。 -- **Agent の内部処理を収集**：Agent の判断をデバッグする際、内部のモデル呼び出しやツール呼び出しを確認するにはオンにします。オフにすると内部の呼び出しは省かれますが、トレースには Agent の実行やワークフローノード自体が残ります。 -- **内容を収集**：これらの実行の入出力を監視サービスに送信する場合にのみオンにします。オフでも、実行時間や token 情報、ステータスは確認できます。 + + ![](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) + + +Weave に切り替えると、ダッシュボードで Dify アプリケーションの詳細な操作ログを確認できます。 + + + ![](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) + + +Weave を通じた詳細な LLM 操作ログは、Dify アプリケーションのパフォーマンスを最適化するのに役立ちます。 -これらの設定は、Agent アプリに適用されます。新しい Agent ノードを含む Workflow または Chatflow アプリも対象です。このようなワークフローでは、他のノードの入出力も **内容を収集** の設定に従います。それ以外のアプリでは、入出力が送信される場合があります。その内容を監視サービスに送信できない場合は、トレースを無効にしておいてください。 +設定を保存してトレースを有効にしたら、アプリを再実行し、監視サービスに新しいトレースが表示されるか確認してください。トレースは非同期で送信されます。設定の保存だけでは、トレースの到着は確認できません。 + +Agent アプリや [新しい Agent ノード](/ja/self-host/use-dify/nodes/agent#new-agent) を使うワークフローでは、デプロイ設定で `OPS_AGENT_TRACE_ENABLED=true` と `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true` の両方を有効にしてください。詳しくは [環境変数](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) を参照してください。これらのアプリでは **内容を収集** がデフォルトでオフになり、ワークフロー全体の入力と出力を制御します。それ以外のアプリでは、入力と出力が送信される場合があります。 -新しい Agent ノードには、そのノードを含む Workflow または Chatflow アプリのトレース設定が適用されます。ワークフローツール内での Agent 呼び出しは、親の Agent のトレースには含まれません。 +### モニタリングデータリスト + +Dify は処理を階層構造としてエクスポートします。メッセージの下には `llm` 呼び出しがあり、Chatflow のメッセージの下にはワークフローとノードの処理があります。監視サービスのトレース ID とスパン ID は Dify の識別子から生成され、データベースの ID をそのままコピーしたものではありません。トークン使用量のネイティブフィールドは、モデル呼び出しにのみ設定されます。 + +以下の詳細リストは、Dify の元レコードとメタデータを説明しています。エクスポートされるのは、関連する利用可能な値のみです。元レコード全体をそのまま送信するわけではありません。 + +#### **Workflow/Chatflow トレース情報** + +**Workflow と Chatflow を追跡するために使用** + +| ワークフロー | Weave トレース | +| ------------------------------------ | ---------------------------- | +| workflow_run_id | id | +| user_id | attributes.user_id | +| workflow | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| モデルトークン消費量（LLM 呼び出し） | summary.usage（モデルごと） | +| metadata | attributes | +| error | exception | +| セッション ID | thread_id | +| 親スパン（存在する場合） | parent_id | + +**ワークフロートレース情報** + +* workflow_id - ワークフローの一意の識別子 +* conversation_id - 会話 ID +* workflow_run_id - 現在の実行の ID +* tenant_id - テナント ID +* elapsed_time - 現在の実行にかかった時間 +* status - 実行ステータス +* version - ワークフローバージョン +* total_tokens - 現在の実行で使用されたトークンの総数 +* file_list - 処理されたファイルのリスト +* triggered_from - 現在の実行をトリガーしたソース +* workflow_run_inputs - 現在の実行の入力データ +* workflow_run_outputs - 現在の実行の出力データ +* error - 現在の実行中に発生したエラー +* query - 実行中に使用されたクエリ +* workflow_app_log_id - Workflow アプリケーションログ ID +* message_id - 関連するメッセージ ID +* start_time - 実行の開始時間 +* end_time - 実行の終了時間 +* workflow node executions - ワークフローノード実行に関する情報 +* メタデータ + * workflow_id - ワークフローの一意の識別子 + * conversation_id - 会話 ID + * workflow_run_id - 現在の実行の ID + * tenant_id - テナント ID + * elapsed_time - 現在の実行にかかった時間 + * status - 実行ステータス + * version - ワークフローバージョン + * total_tokens - 現在の実行で使用されたトークンの総数 + * file_list - 処理されたファイルのリスト + * triggered_from - 現在の実行をトリガーしたソース + +#### **メッセージトレース情報** + +**LLM 関連の会話を追跡するために使用** + +| チャット | Weave トレース | +| ---------------------------------- | ----------------------------- | +| message_id | id | +| end_user_session_id | attributes.end_user_session_id | +| message | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| モデルトークン消費量（LLM 呼び出し） | summary.usage（モデルごと） | +| metadata | attributes | +| error | exception | +| セッション ID | thread_id | + +**メッセージトレース情報** + +* message_id - メッセージ ID +* message_data - メッセージデータ +* end_user_session_id - ユーザーセッション ID +* conversation_model - 会話モード +* message_tokens - メッセージ内のトークン数 +* answer_tokens - 回答内のトークン数 +* total_tokens - メッセージと回答内のトークンの総数 +* error - エラー情報 +* inputs - 入力データ +* outputs - 出力データ +* file_list - 処理されたファイルのリスト +* start_time - 開始時間 +* end_time - 終了時間 +* conversation_mode - 会話モード +* メタデータ + * conversation_id - 会話 ID + * ls_provider - モデルプロバイダー + * ls_model_name - モデル ID + * status - メッセージステータス + * from_end_user_id - 送信ユーザーの ID + * from_account_id - 送信アカウントの ID + * agent_based - メッセージがエージェントベースかどうか + * workflow_run_id - ワークフロー実行 ID + * from_source - メッセージソース + +#### **モデレーショントレース情報** + +**会話モデレーションを追跡するために使用** + +| モデレーション | Weave トレース | +| ------------- | ----------------------- | +| user_id | attributes.user_id | +| "moderation" | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| action, flagged | output | +| metadata | attributes | +| message_id | parent_id | + +**モデレーショントレース情報** + +* message_id - メッセージ ID +* user_id: ユーザーID +* workflow_app_log_id - Workflow アプリケーションログ ID +* inputs - モデレーション入力データ +* message_data - メッセージデータ +* flagged - コンテンツが注意対象としてフラグ付けされているかどうか +* action - 取られた特定のアクション +* preset_response - プリセット応答 +* start_time - モデレーション開始時間 +* end_time - モデレーション終了時間 +* メタデータ + * message_id - メッセージ ID + * action - 取られた特定のアクション + * preset_response - プリセット応答 + +#### **提案質問トレース情報** + +**提案された質問を追跡するために使用** + +| 提案質問 | Weave トレース | +| ---------------------- | ----------------------- | +| user_id | attributes.user_id | +| suggested_question | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| suggested_question | output | +| metadata | attributes | +| message_id | parent_id | + +**メッセージトレース情報** + +* message_id - メッセージ ID +* message_data - メッセージデータ +* inputs - 入力内容 +* outputs - 出力内容 +* start_time - 開始時間 +* end_time - 終了時間 +* total_tokens - トークン数 +* status - メッセージステータス +* error - エラー情報 +* from_account_id - 送信アカウントの ID +* agent_based - メッセージがエージェントベースかどうか +* from_source - メッセージソース +* model_provider - モデルプロバイダー +* model_id - モデル ID +* suggested_question - 提案された質問 +* level - ステータスレベル +* status_message - ステータスメッセージ +* メタデータ + * message_id - メッセージ ID + * ls_provider - モデルプロバイダー + * ls_model_name - モデル ID + * status - メッセージステータス + * from_end_user_id - 送信ユーザーの ID + * from_account_id - 送信アカウントの ID + * workflow_run_id - ワークフロー実行 ID + * from_source - メッセージソース + +#### **データセット検索トレース情報** + +**ナレッジベース検索を追跡するために使用** + +| データセット検索 | Weave トレース | +| --------------------- | ----------------------- | +| user_id | attributes.user_id | +| dataset_retrieval | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| documents | output | +| metadata | attributes | +| message_id | parent_id | + +**データセット検索トレース情報** + +* message_id - メッセージ ID +* inputs - 入力内容 +* documents - ドキュメントデータ +* start_time - 開始時間 +* end_time - 終了時間 +* message_data - メッセージデータ +* メタデータ + * message_id - メッセージ ID + * ls_provider - モデルプロバイダー + * ls_model_name - モデル ID + * status - メッセージステータス + * from_end_user_id - 送信ユーザーの ID + * from_account_id - 送信アカウントの ID + * agent_based - メッセージがエージェントベースかどうか + * workflow_run_id - ワークフロー実行 ID + * from_source - メッセージソース + +#### **ツールトレース情報** + +**ツール呼び出しを追跡するために使用** + +| ツール | Weave トレース | +| --------------------- | ----------------------- | +| user_id | attributes.user_id | +| tool_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| tool_inputs | inputs | +| tool_outputs | output | +| metadata | attributes | +| message_id | parent_id | -## 新しいトレースの確認 +#### **ツールトレース情報** -1. Dify アプリに新しいリクエストを送信し、実行が完了するまで待ちます。 -2. **アプリのパフォーマンスの追跡** で、**織る** の **見る** をクリックして設定したプロジェクトを開きます。 -3. 実行時刻を手がかりに新しい呼び出しを探し、開いて子の呼び出しを確認します。 +* message_id - メッセージ ID +* tool_name - ツール名 +* start_time - 開始時間 +* end_time - 終了時間 +* tool_inputs - ツール入力 +* tool_outputs - ツール出力 +* message_data - メッセージデータ +* error - エラー情報（もしあれば） +* inputs - メッセージの入力 +* outputs - メッセージの出力 +* tool_config - ツール設定 +* time_cost - 時間コスト +* tool_parameters - ツールパラメータ +* file_url - 関連ファイルの URL +* メタデータ + * message_id - メッセージ ID + * tool_name - ツール名 + * tool_inputs - ツール入力 + * tool_outputs - ツール出力 + * tool_config - ツール設定 + * time_cost - 時間コスト + * error - エラー情報（もしあれば） + * tool_parameters - ツールパラメータ + * message_file_id - メッセージファイル ID + * created_by_role - 作成者のロール + * created_user_id - 作成者のユーザーID -実行が完了してからトレースが表示されるまで、時間がかかる場合があります。 +**名前生成トレース情報** -## トラブルシューティング +**会話タイトル生成を追跡するために使用** - - - 保存時には、プロジェクトが存在し、書き込み可能であることと、トレースサーバーに接続できることを確認します。Weave が選択され、トレースが有効になっていることを確認してください。Weave で、Dify に設定したエンティティとプロジェクトを開き、アプリを再度実行します。 +| 名前生成 | Weave トレース | +| ----------------- | ----------------------- | +| user_id | attributes.user_id | +| generate_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| metadata | attributes | - 新しい実行がまだ表示されない場合は、管理者にワーカーログと [トレース配信キュー](/ja/self-host/deploy/configuration/environments#llmops-トレース配信) の確認を依頼してください。 - - - Dify の API とワーカーから接続できるアドレスを指定する必要があります。コンテナ内の `localhost` は、そのコンテナ自身を指します。監視サーバーに到達できるホスト名を使用してください。 +**名前生成トレース情報** - プライベート HTTP エンドポイントを使う場合は、管理者に [SSRF プロキシの許可リスト](/ja/self-host/deploy/configuration/environments#ssrf-プロキシ) の確認を依頼します。必要な送信先だけを許可してください。 - - +* conversation_id - 会話 ID +* inputs - 入力データ +* outputs - 生成された会話名 +* start_time - 開始時間 +* end_time - 終了時間 +* tenant_id - テナント ID +* メタデータ + * conversation_id - 会話 ID + * tenant_id - テナント ID diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx index aa2e7c1bf..305d00082 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-aliyun.mdx @@ -1,82 +1,206 @@ --- title: 集成阿里云云监控 -sidebarTitle: 阿里云云监控 -description: 通过 OpenTelemetry 将 Dify 应用的追踪数据发送至阿里云云监控（ARMS） --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-aliyun)。 -## 连接应用 +## 什么是阿里云云监控 -让部署管理员参考 [阿里云接入说明](https://help.aliyun.com/en/arms/tracing-analysis/before-you-begin)，提供 License Key 和 HTTP 追踪 URL。管理员应选择 Dify 服务可访问的地域和网络地址。 +阿里云提供的全托管免运维可观测平台，一键开启 Dify 应用的监控追踪和评估。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **云监控** 的 **配置**，填写连接信息： + +阿里云云监控原生支持 Python/Golang/Java 应用通过 [LoongSuite](https://github.com/alibaba/loongsuite-python-agent) +探针 & 开源 OpenTelemetry 探针接入，在一键开启 Dify 大模型应用监控外，还支持通过无侵入探针对 Dify 组件及其上下游依赖的全链路可观测。 +更多详情，请参考 [阿里云官方文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/user-guide/model-application)。 + -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **License Key** | 是 | 采集器的认证密钥，与端点分开填写。 | -| **Endpoint** | 是 | 采集器的 HTTP(S) 基础 URL，可包含端口号。 | -| **App Name** | 是 | 自定义应用名称，用于在 ARMS 控制台中显示。 | +## 如何配置云监控 -将 HTTP 追踪 URL 中 `/adapt_` 之前的部分填入 **Endpoint**，将认证令牌 填入 **License Key**。例如，HTTP 追踪 URL 为： +### 1. 获取阿里云 Endpoint 和 License Key -```text -https://tracing-analysis-dc-hz.aliyuncs.com/adapt_example-key/api/otlp/traces -``` +1. 登录 [ARMS 控制台](https://arms.console.aliyun.com/)，在左侧导航栏单击 **接入中心**。 +2. 在 **服务端应用** 区域单击 **OpenTelemetry** 卡片。 +3. 在弹出的 **OpenTelemetry** 面板中选择数据上报方式为 **HTTP**，并依据实际部署情况选择连接方式和地域。 -- **Endpoint**：`https://tracing-analysis-dc-hz.aliyuncs.com` -- **License Key**：`example-key` + + ![P976945](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/3938280571/p976945.png) + -保留 HTTP 端点中的端口号；此处不能使用 `8090` 等 gRPC 端口。 +4. 保存 **公网接入点（Endpoint）** 和 **鉴权 Token（License Key）**。 +> **说明** +> **Endpoint** 填写 HTTP(S) 基础 URL；若 HTTP 收集器要求端口号，需要保留。Token 单独填入 **License Key**。不要包含 `adapt_` 或数据接入路径，也不要使用 gRPC 端口 `8090`；Dify 会自动构造 OTLP/HTTP 数据接入 URL。 -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 云监控 会替换当前选择。 +### 2. 将云监控与 Dify 集成 -编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 + + 需要 Dify v1.6.0 或更高版本。 + -## Dify 发送的数据 +1. 登录 **Dify 控制台**，并进入需要监控的 Dify 应用。 +2. 在左侧导航栏单击 **监测**。 +3. 单击 **追踪应用性能**，然后在 **云监控** 区域单击 **配置**。 -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 + + ![P984812](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9647222571/p984812.png) + -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 +4. 在弹出的对话框中输入步骤 1 获取的 **License Key** 和 **Endpoint**，并自定义 **App Name**（ARMS 控制台显示的应用名称），然后单击 **保存并启用**。 -在阿里云云监控中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充该平台的内置费用字段。 +## 在云监控中查看监控数据 -### 采集 Agent 调用和内容 +配置完成后，Dify 内应用的调试或生产数据可以在 **云监控** 中进行监控。 - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +### 方式一：从 Dify 应用跳转 ARMS 控制台 -在应用的追踪设置中，找到 **Agent 数据采集**： +在 Dify 控制台选择已开启应用追踪的应用，进入 **追踪配置**，在 **云监控** 区域单击 **查看**。 -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 + + ![P984818](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9647222571/p984818.png) + - -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 - +### 方式二：直接在 ARMS 控制台查看 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +在 ARMS 控制台的 **LLM 应用监控 > 应用列表** 页面进入对应的 Dify 应用。 -## 验证新的追踪记录 +## 接入更多数据 -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **云监控** 的 **查看**，打开 ARMS 大模型控制台。 -3. 找到填写的应用名称，再按运行时间定位新的追踪记录，查看其中的子 span。 +云监控提供了多语言无侵入探针，支持接入 Dify 集群的各个组件，实现全链路追踪。 -运行结束后，追踪记录可能需要一段时间才会显示。 +| Dify 组件 | 探针 | 详情 | +|---------------|--------------------|----------------| +| Nginx | OpenTelemetry 探针 | [使用 OpenTelemetry 对 Nginx 进行链路追踪](https://help.aliyun.com/zh/opentelemetry/user-guide/use-opentelemetry-to-perform-tracing-analysis-on-nginx) | +| Api | LoongSuite-Python 探针 | [loongsuite-python-agent](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md) | +| Sandbox | LoongSuite-Go 探针 | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | +| Worker | OpenTelemetry 探针 | [通过 OpenTelemetry 上报 Python 应用数据](https://help.aliyun.com/zh/opentelemetry/user-guide/use-managed-service-for-opentelemetry-to-submit-the-trace-data-of-python-applications) | +| Plugin-Daemon | LoongSuite-Go 探针 | [loongsuite-go-agent](https://github.com/alibaba/loongsuite-go-agent/blob/main/README.md) | -## 故障排查 - - - - 保存配置时会测试采集器是否可访问，不会创建实际追踪记录。确认已选择云监控并启用追踪。在阿里云云监控中，按配置的应用名称找到并打开应用，然后重新运行 Dify 应用。 + +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 + - 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +## 监测数据清单 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +云监控支持采集 Dify 的 Workflow/Chatflow/Chat/Agent 应用，采集数据包括工作流和工作流节点的执行明细，涵盖模型调用、工具调用、知识检索和各类流程节点的执行明细数据以及会话和用户信息等元数据 + +### Workflow/Chatflow Trace 信息 + +**Workflow Trace Info** + +* workflow\_id - Workflow 的唯一标识 +* conversation\_id - 对话 ID +* workflow\_run\_id - 此次运行的 ID +* tenant\_id - 租户 ID +* elapsed\_time - 此次运行耗时 +* status - 运行状态 +* version - Workflow 版本 +* total\_tokens - 此次运行使用的 token 总数 +* file\_list - 处理的文件列表 +* triggered\_from - 触发此次运行的来源 +* workflow\_run\_inputs - 此次运行的输入数据 +* workflow\_run\_outputs - 此次运行的输出数据 +* error - 此次运行中发生的错误 +* query - 运行时使用的查询 +* workflow\_app\_log\_id - Workflow 应用日志 ID +* message\_id - 关联的消息 ID +* start\_time - 运行开始时间 +* end\_time - 运行结束时间 +* workflow node executions - workflow 节点运行信息 +* Metadata + * workflow\_id - Workflow 的唯一标识 + * conversation\_id - 对话 ID + * workflow\_run\_id - 此次运行的 ID + * tenant\_id - 租户 ID + * elapsed\_time - 此次运行耗时 + * status - 运行状态 + * version - Workflow 版本 + * total\_tokens - 此次运行使用的 token 总数 + * file\_list - 处理的文件列表 + * triggered\_from - 触发来源 + +### Message Trace 信息 + +**Message Trace Info** + +* message\_id - 消息 ID +* message\_data - 消息数据 +* end\_user\_session\_id - 用户的 session\_id +* conversation\_model - 对话模式 +* message\_tokens - 消息中的令牌数 +* answer\_tokens - 回答中的令牌数 +* total\_tokens - 消息和回答中的总令牌数 +* error - 错误信息 +* inputs - 输入数据 +* outputs - 输出数据 +* file\_list - 处理的文件列表 +* start\_time - 开始时间 +* end\_time - 结束时间 +* conversation\_mode - 对话模式 +* Metadata + * conversation\_id - 消息所属对话的 ID + * ls\_provider - 模型提供者 + * ls\_model\_name - 模型 ID + * status - 消息状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户的 ID + * agent\_based - 是否基于代理 + * workflow\_run\_id - 工作流运行 ID + * from\_source - 消息来源 + * message\_id - 消息 ID + +### Dataset Retrieval Trace 信息 + +**Dataset Retrieval Trace Info** + +* message\_id - 消息 ID +* inputs - 输入内容 +* documents - 文档数据 +* start\_time - 开始时间 +* end\_time - 结束时间 +* message\_data - 消息数据 +* Metadata + * message\_id 消息 ID + * ls\_provider 模型提供者 + * ls\_model\_name 模型 ID + * status 消息状态 + * from\_end\_user\_id 发送用户的 ID + * from\_account\_id 发送账户的 ID + * agent\_based 是否基于代理 + * workflow\_run\_id 工作流运行 ID + * from\_source 消息来源 + +### Tool Trace 信息 + +**Tool Trace Info** + +* message\_id 消息 ID +* tool\_name 工具名称 +* start\_time 开始时间 +* end\_time 结束时间 +* tool\_inputs 工具输入 +* tool\_outputs 工具输出 +* message\_data 消息数据 +* error 错误信息，如果存在 +* inputs 消息的输入内容 +* outputs 消息的回答内容 +* tool\_config 工具配置 +* time\_cost 时间成本 +* tool\_parameters 工具参数 +* file\_url 关联文件的 URL +* Metadata + * message\_id 消息 ID + * tool\_name 工具名称 + * tool\_inputs 工具输入 + * tool\_outputs 工具输出 + * tool\_config 工具配置 + * time\_cost 时间成本 + * error 错误信息 + * tool\_parameters 工具参数 + * message\_file\_id 消息文件 ID + * created\_by\_role 创建者角色 + * created\_user\_id 创建者用户 ID \ No newline at end of file diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx index fe7fe39a9..8477312df 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-arize.mdx @@ -1,74 +1,331 @@ --- title: 集成 Arize -sidebarTitle: Arize -description: 将 Dify 应用连接至 Arize，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-arize)。 -## 连接应用 +### Arize 简介 -在 Arize 的 **Settings** > **API Keys** 中获取 API 密钥和当前 Space ID，详见 [Arize 快速入门](https://arize.com/docs/ax/quickstarts)。确定目标项目名称。如需连接 Phoenix，参考 [Phoenix 集成](/zh/self-host/use-dify/monitor/integrations/integrate-phoenix)。 +[Arize AX](https://arize.com/products/ax/) 是 [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-arize-self-host) 推出的全功能平台，为 LLM 和 Agent 驱动的应用提供可观测性、在线与离线评估、监控和实验能力。它面向生产环境团队、AI 原生公司和企业，支持托管云与企业自部署两种部署方式。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Arize** 的 **配置**，填写连接信息： +如需用于本地开发、实验或单容器自部署的开源方案，可改用 [Phoenix 集成](/zh/self-host/use-dify/monitor/integrations/integrate-phoenix)。 -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **API Key** | 是 | 有数据写入权限的 Arize API 密钥。 | -| **Space ID** | 是 | 接收追踪数据的 Arize 空间。 | -| **项目** | 是 | 目标项目名称。 | -| **Endpoint** | 否 | 默认为 `https://otlp.arize.com`。使用自定义采集器时，填写管理员提供的地址。 | +追踪数据接入后，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [LLM 评估指南](https://arize.com/resources/llm-evaluation/)，了解如何用追踪数据调试故障、评估 Agent 行为、监控模型质量。 -自定义 **Endpoint** 必须支持 OTLP/gRPC。向管理员获取主机名和端口，不要包含 `/v1/traces` 等 HTTP 路径。 +### 配置 Arize -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Arize 会替换当前选择。 +本章节将指引你注册 Arize 并将其集成至 Dify 平台内。 -编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将 **API Key** 和 **Space ID** 留空即可保留原值；如果更改端点，则需重新填写这两项。 +#### 1. 注册/登录 [Arize](https://app.arize.com/auth/join) -## Dify 发送的数据 +### 2. 获取 Arize API 密钥 -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +从右上角的用户菜单中获取 Arize API 密钥。点击 **API Key**，然后点击 API Key 进行复制： -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 + + ![](https://i.ibb.co/JwBmQxnf/dify-docs-arize-api-key.png) + -在 Arize 中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充 Arize 的内置费用字段。 +### 3. 集成 Arize 与 Dify -### 采集 Agent 调用和内容 +在 Dify 应用中配置 Arize。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - + + ![](https://i.ibb.co/v6cL6rPs/dify-docs-arize-in-use.png) + + +点击配置后，将 **API Key**、**Space ID** 和 **项目** 名称粘贴到配置中并保存。**Endpoint** 默认为 `https://otlp.arize.com`，必须指向 OTLP/gRPC 收集器。URL 中的路径不会使用，不要填写 HTTP `/v1/traces` 地址。 -在应用的追踪设置中，找到 **Agent 数据采集**： + + ![](https://i.ibb.co/m5Xww8gL/dify-docs-arize-config.png) + -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 +成功保存后，你可以在当前页面查看监控状态。 + + + ![](https://i.ibb.co/xtggVmb7/dify-docs-arize-in-service.png) + -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +## 监控数据列表 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +### **Workflow/Chatflow 追踪信息** + +**用于追踪 Workflow 和 Chatflow** + +| 工作流 | Arize 追踪 | +| ---------------------------------- | -------------------------- | +| workflow_run_id | span_id | +| user_id | metadata.user_id | +| workflow | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| 模型 token 消耗（LLM 调用） | llm.token_count.prompt / completion / total | +| metadata | metadata | +| error | status.code / status.message | +| 会话 ID | session.id | + +**工作流追踪信息** + +- workflow_id - 工作流唯一标识符 +- conversation_id - 对话 ID +- workflow_run_id - 当前运行的 ID +- tenant_id - 租户 ID +- elapsed_time - 当前运行所用时间 +- status - 运行状态 +- version - 工作流版本 +- total_tokens - 当前运行使用的总令牌数 +- file_list - 处理的文件列表 +- triggered_from - 触发当前运行的来源 +- workflow_run_inputs - 当前运行的输入数据 +- workflow_run_outputs - 当前运行的输出数据 +- error - 当前运行期间遇到的错误 +- query - 运行期间使用的查询 +- workflow_app_log_id - Workflow 应用日志 ID +- message_id - 关联的消息 ID +- start_time - 运行开始时间 +- end_time - 运行结束时间 +- workflow node executions - 工作流节点执行信息 +- 元数据 + - workflow_id - 工作流唯一标识符 + - conversation_id - 对话 ID + - workflow_run_id - 当前运行的 ID + - tenant_id - 租户 ID + - elapsed_time - 当前运行所用时间 + - status - 运行状态 + - version - 工作流版本 + - total_tokens - 当前运行使用的总令牌数 + - file_list - 处理的文件列表 + - triggered_from - 触发当前运行的来源 + +#### **消息追踪信息** + +**用于追踪 LLM 相关对话** + +| 聊天 | Arize Trace | +| ------------------------------- | --------------------------- | +| message_id | span_id | +| end_user_session_id | metadata.end_user_session_id | +| message | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| 模型 token 消耗（LLM 调用） | llm.token_count.prompt / completion / total | +| metadata | metadata | +| 会话 ID | session.id | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- end_user_session_id - 用户会话 ID +- conversation_model - 对话模式 +- message_tokens - 消息中的令牌数 +- answer_tokens - 答案中的令牌数 +- total_tokens - 消息和答案中的总令牌数 +- error - 错误信息 +- inputs - 输入数据 +- outputs - 输出数据 +- file_list - 处理的文件列表 +- start_time - 开始时间 +- end_time - 结束时间 +- conversation_mode - 对话模式 +- 元数据 + - conversation_id - 对话 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 消息是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **审核追踪信息** + +**用于追踪对话审核** + +| 审核 | Arize Tool | +| -------------- | ----------------- | +| user_id | metadata.user_id | +| "moderation" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| action, flagged | output.value | +| metadata | metadata | + +**审核追踪信息** + +- message_id - 消息 ID +- user_id - 用户 ID +- workflow_app_log_id - Workflow 应用日志 ID +- inputs - 审核输入数据 +- message_data - 消息数据 +- flagged - 内容是否被标记需要注意 +- action - 采取的具体行动 +- preset_response - 预设响应 +- start_time - 审核开始时间 +- end_time - 审核结束时间 +- 元数据 + - message_id - 消息 ID + - action - 采取的具体行动 + - preset_response - 预设响应 + +#### **建议问题追踪信息** + +**用于追踪建议问题** + +| 建议问题 | Arize Trace | +| --------------------- | ----------------- | +| user_id | metadata.user_id | +| "suggested_question" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| suggested_question | output.value | +| metadata | metadata | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- inputs - 输入内容 +- outputs - 输出内容 +- start_time - 开始时间 +- end_time - 结束时间 +- total_tokens - 令牌数量 +- status - 消息状态 +- error - 错误信息 +- from_account_id - 发送账户的 ID +- agent_based - 是否基于代理 +- from_source - 消息来源 +- model_provider - 模型供应商 +- model_id - 模型 ID +- suggested_question - 建议问题 +- level - 状态级别 +- status_message - 状态消息 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **数据集检索追踪信息** + +**用于追踪知识库检索** + +| 数据集检索 | Arize Retriever | +| ------------------- | ----------------- | +| user_id | metadata.user_id | +| "dataset_retrieval" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| documents | output.value | +| metadata | metadata | +| message_id | parent_span_id | + +**数据集检索追踪信息** + +- message_id - 消息 ID +- inputs - 输入内容 +- documents - 文档数据 +- start_time - 开始时间 +- end_time - 结束时间 +- message_data - 消息数据 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **工具追踪信息** + +**用于追踪工具调用** + +| 工具 | Arize Tool | +| -------------------- | ----------------- | +| user_id | metadata.user_id | +| tool_name | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| tool_inputs | input.value | +| tool_outputs | output.value | +| metadata | metadata | -## 验证新的追踪记录 +#### **工具追踪信息** -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **Arize** 的 **查看**。如果快捷链接不可用，直接打开 Arize 空间和项目。 -3. 按运行时间找到新的追踪记录，打开后查看子 span。 +- message_id - 消息 ID +- tool_name - 工具名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tool_inputs - 工具输入 +- tool_outputs - 工具输出 +- message_data - 消息数据 +- error - 错误信息（如果有） +- inputs - 消息的输入 +- outputs - 消息的输出 +- tool_config - 工具配置 +- time_cost - 时间消耗 +- tool_parameters - 工具参数 +- file_url - 关联文件的 URL +- 元数据 + - message_id - 消息 ID + - tool_name - 工具名称 + - tool_inputs - 工具输入 + - tool_outputs - 工具输出 + - tool_config - 工具配置 + - time_cost - 时间消耗 + - error - 错误信息（如果有） + - tool_parameters - 工具参数 + - message_file_id - 消息文件 ID + - created_by_role - 创建者角色 + - created_user_id - 创建者用户 ID -运行结束后，追踪记录可能需要一段时间才会显示。 +#### **生成名称追踪信息** -## 故障排查 +**用于追踪对话标题生成** - - - 保存配置时会测试采集器是否可访问，不会创建实际追踪记录。确认已选择 Arize 并启用追踪。在 Arize 中打开配置的空间和项目，然后重新运行应用。 +| 生成名称 | Arize Tool | +| ---------------------------- | ----------------- | +| user_id | metadata.user_id | +| generate_name | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| metadata | metadata | - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问 gRPC 采集器。让管理员检查采集器的主机名、端口和网络访问权限。填写可访问的服务器地址，不支持 `localhost` 等回环地址。 - - +**生成名称追踪信息** -评估已采集的追踪数据时，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [大语言模型评估指南](https://arize.com/resources/llm-evaluation/)。 +- conversation_id - 对话 ID +- inputs - 输入数据 +- outputs - 生成的对话名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tenant_id - 租户 ID +- 元数据 + - conversation_id - 对话 ID + - tenant_id - 租户 ID diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx index d2325f362..6418340c1 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-langfuse.mdx @@ -1,77 +1,619 @@ --- title: 集成 Langfuse -sidebarTitle: Langfuse -description: 将 Dify 应用连接至 Langfuse，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-langfuse)。 -## 连接应用 +### 什么是 Langfuse -创建 Langfuse 项目，在 **Project Settings** > **API Keys** 中获取 [API 密钥](https://langfuse.com/faq/all/where-are-langfuse-api-keys)。使用 Langfuse Cloud 时，选择 [所在区域的基础 URL](https://langfuse.com/docs/api-and-data-platform/features/public-api#select-the-regional-base-url)，不要包含 `/api/public` 后缀。自部署实例的基础 URL 可向其管理员获取。 +Langfuse 是一个开源的大型语言模型工程平台，帮助团队协作调试、分析和迭代他们的应用。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Langfuse** 的 **配置**，填写连接信息： + + 介绍 Langfuse: [https://langfuse.com/](https://langfuse.com/) + -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **密钥** | 是 | 项目的密钥。 | -| **公钥** | 是 | 与密钥配套的公钥。 | -| **Host** | 是 | Langfuse 实例的 HTTP(S) 基础 URL。 | +### 如何配置 Langfuse - -此集成需要通过 Langfuse 的旧版接收 API `/api/public/ingestion` 接收追踪数据。使用 `events_only` 模式的 Langfuse v4 部署无法接收这些数据。接入前，与 Langfuse 管理员核对 [Langfuse 的数据接收兼容性](https://langfuse.com/docs/api-and-data-platform/features/public-api#ingest-traces-via-the-api)。 - +1. 在[官方网站](https://langfuse.com/)注册并登录 Langfuse +2. 在 Langfuse 中创建一个项目。登录后，点击主页上的 **New** 来创建你自己的项目。该 **项目**将用于与 Dify 中的 **应用**关联，以进行数据监控。 -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Langfuse 会替换当前选择。 + + ![在 Langfuse 中创建一个项目](https://assets-docs.dify.ai/2025/04/34ca6a973c4a1230be659b313b99fd90.png) + -编辑配置时，已保存的凭据不会显示。如果 **Host** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 +编辑项目名称。 -## Dify 发送的数据 + + ![在 Langfuse 中创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/26cfbb94e312a100c39e217fdd0b4406.png) + -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +3. 创建项目 API 凭据。在项目的左侧栏中，点击 **Settings** 打开设置。 -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 + + ![创建项目 API 凭据](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/2ed72a6761f2977201c29e67e5bc634c.png) + -在 Langfuse 中打开一条 generation 记录，可查看采集到的模型调用输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 +在设置中，点击 **Create API Keys** 来创建项目 API 凭据。 -### 采集 Agent 调用和内容 + + ![创建项目 API 凭据](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/3c3fbd5392d37fbccf1f9ef76c54f0bc.png) + - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +复制并保存 **Secret Key**、**Public Key** 和 **Host**。 + + + ![获取 API 密钥配置](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/a2ff67951ce300082d875eae8458c8c7.png) + + +4. 在 Dify 中配置 Langfuse。打开你需要监控的应用，在侧边菜单中打开 **Monitoring**，并在页面上选择 **Tracing app performance**。 + + + ![配置 Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/ebc84b328ad37c0f6dbca6101e1f90ab.png) + + +点击配置后，将在 Langfuse 中创建的 **密钥**、**公钥** 和 **Host** 粘贴到配置中并保存。**Host** 必须填写项目所在区域或自部署实例的基础 URL，不含 `/api/public`。此集成依赖 [旧版数据接入 API](https://langfuse.com/docs/api-and-data-platform/features/public-api)；`events_only` 实例不接受这些追踪数据。 + + + ![配置 Langfuse](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/5bfa409e7a073f133f21146535401512.png) + + +成功保存后，你可以在当前页面查看状态。 -在应用的追踪设置中，找到 **Agent 数据采集**： + + ![查看配置状态](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/monitoring/integrate-external-ops-tools/1aa086a1aead0e29948e7d6d5815d5d1.png) + -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 +### 在 Langfuse 中查看监控数据 + +配置完成后，可以在 Langfuse 中查看 Dify 应用的调试或生产数据。 + + + ![](https://assets-docs.dify.ai/2025/04/a2c02ccc559743b85b0f972aa513e47a.png) + + + + ![](https://assets-docs.dify.ai/2025/04/88f3adfb03f325d2ea800ba5685b9ec9.png) + -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +### 监控数据列表 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +#### 跟踪 Workflow 和 Chatflow 的信息 + +**跟踪 Workflow 和 Chatflow** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WorkflowLangFuse Trace
workflow_run_idid
user_iduserId
workflowname
start\_timetimestamp / startTime
end\_timeendTime（观察记录）
inputsinput
outputsoutput
模型 token 消耗（LLM 调用）usage
metadatametadata
errorlevel（观察记录）
errorstatusMessage（观察记录）
会话 IDsessionId
父 span（如有）parentObservationId（嵌套观察记录）
+**工作流跟踪信息** + +* workflow\_id - 工作流的唯一 ID +* conversation\_id - 对话 ID +* workflow\_run\_id - 此运行时的工作流 ID +* tenant\_id - 租户 ID +* elapsed\_time - 此运行时的经过时间 +* status - 运行时状态 +* version - 工作流版本 +* total\_tokens - 此运行时使用的总标记数 +* file\_list - 处理文件的列表 +* triggered\_from - 触发此运行时的来源 +* workflow\_run\_inputs - 此工作流的输入 +* workflow\_run\_outputs - 此工作流的输出 +* error - 错误信息 +* query - 运行时使用的查询 +* workflow\_app\_log\_id - Workflow 应用日志 ID +* message\_id - 相关消息 ID +* start\_time - 此运行时的开始时间 +* end\_time - 此运行时的结束时间 +* workflow node executions - 工作流节点运行时信息 +* 元数据 + * workflow\_id - 工作流的唯一 ID + * conversation\_id - 对话 ID + * workflow\_run\_id - 此运行时的工作流 ID + * tenant\_id - 租户 ID + * elapsed\_time - 此运行时的经过时间 + * status - 操作状态 + * version - 工作流版本 + * total\_tokens - 此运行时使用的总标记数 + * file\_list - 处理文件的列表 + * triggered\_from - 触发此运行时的来源 + +#### 消息跟踪信息 + +**用于跟踪大型语言模型对话** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MessageLangFuse Generation/Trace
message\_idid
end\_user\_session\_iduserId
messagename
start\_timetimestamp / startTime
end\_timeendTime（观察记录）
inputsinput
outputsoutput
模型 token 消耗（LLM 调用）usage
metadatametadata
errorlevel（观察记录）
errorstatusMessage（观察记录）
会话 IDsessionId
+**消息跟踪信息** + +* message\_id - 消息 ID +* message\_data - 消息数据 +* end\_user\_session\_id - 用户会话 ID +* conversation\_model - 对话模型 +* message\_tokens - 消息标记数 +* answer\_tokens - 回答标记数 +* total\_tokens - 消息和回答的总标记数 +* error - 错误信息 +* inputs - 输入数据 +* outputs - 输出数据 +* file\_list - 处理文件的列表 +* start\_time - 开始时间 +* end\_time - 结束时间 +* conversation\_mode - 对话模式 +* 元数据 + * conversation\_id - 对话 ID + * ls\_provider - 模型供应商 + * ls\_model\_name - 模型 ID + * status - 消息状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户的 ID + * agent\_based - 是否基于 Agent + * workflow\_run\_id - 此运行时的工作流 ID + * from\_source - 消息来源 + * message\_id - 消息 ID + +#### 审核跟踪信息 + +**用于跟踪对话审核** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModerationLangFuse Generation/Trace
user\_idmetadata.user_id
moderationname
start\_timestartTime
end\_timeendTime（观察记录）
inputsinput
action, flaggedoutput
metadatametadata
message\_idtraceId
+**消息跟踪信息** + +* message\_id - 消息 ID +* user\_id - 用户 ID +* workflow\_app\_log\_id - Workflow 应用日志 ID +* inputs - 审核输入数据 +* message\_data - 消息数据 +* flagged - 是否标记为关注 +* action - 实施的具体动作 +* preset\_response - 预设响应 +* start\_time - 审核开始时间 +* end\_time - 审核结束时间 +* 元数据 + * message\_id - 消息 ID + * action - 实施的具体动作 + * preset\_response - 预设响应 + +#### 建议问题跟踪信息 + +**用于跟踪建议问题** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Suggested QuestionLangFuse Generation/Trace
user\_idmetadata.user_id
suggested\_questionname
start\_timestartTime
end\_timeendTime（观察记录）
inputsinput
suggested_questionoutput
metadatametadata
message\_idtraceId
+**消息跟踪信息** + +* message\_id - 消息 ID +* message\_data - 消息数据 +* inputs - 输入数据 +* outputs - 输出数据 +* start\_time - 开始时间 +* end\_time - 结束时间 +* total\_tokens - 总标记数 +* status - 消息状态 +* error - 错误信息 +* from\_account\_id - 发送账户 ID +* agent\_based - 是否基于 Agent +* from\_source - 消息来源 +* model\_provider - 模型供应商 +* model\_id - 模型 ID +* suggested\_question - 建议问题 +* level - 状态级别 +* status\_message - 消息状态 +* 元数据 + * message\_id - 消息 ID + * ls\_provider - 模型供应商 + * ls\_model\_name - 模型 ID + * status - 消息状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户 ID + * workflow\_run\_id - 此运行时的工作流 ID + * from\_source - 消息来源 + +#### 数据集检索跟踪信息 + +**用于跟踪知识库检索** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dataset RetrievalLangFuse Generation/Trace
user\_idmetadata.user_id
dataset\_retrievalname
start\_timestartTime
end\_timeendTime（观察记录）
inputsinput
documentsoutput
metadatametadata
message\_idtraceId
+**数据集检索跟踪信息** + +* message\_id - 消息 ID +* inputs - 输入消息 +* documents - 文档数据 +* start\_time - 开始时间 +* end\_time - 结束时间 +* message\_data - 消息数据 +* 元数据 + * message\_id - 消息 ID + * ls\_provider - 模型供应商 + * ls\_model\_name - 模型 ID + * status - 模型状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户的 ID + * agent\_based - 是否基于 Agent + * workflow\_run\_id - 此运行时的工作流 ID + * from\_source - 消息来源 + +#### 工具跟踪信息 + +**用于跟踪工具调用** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolLangFuse Generation/Trace
user\_idmetadata.user_id
tool\_namename
start\_timestartTime
end\_timeendTime（观察记录）
tool_inputsinput
tool_outputsoutput
metadatametadata
message\_idtraceId
+**工具跟踪信息** + +* message\_id - 消息 ID +* tool\_name - 工具名称 +* start\_time - 开始时间 +* end\_time - 结束时间 +* tool\_inputs - 工具输入 +* tool\_outputs - 工具输出 +* message\_data - 消息数据 +* error - 错误信息（如果存在） +* inputs - 消息输入 +* outputs - 消息输出 +* tool\_config - 工具配置 +* time\_cost - 时间消耗 +* tool\_parameters - 工具参数 +* file\_url - 相关文件的 URL +* 元数据 + * message\_id - 消息 ID + * tool\_name - 工具名称 + * tool\_inputs - 工具输入 + * tool\_outputs - 工具输出 + * tool\_config - 工具配置 + * time\_cost - 时间消耗 + * error - 错误信息 + * tool\_parameters - 工具参数 + * message\_file\_id - 消息文件 ID + * created\_by\_role - 创建者角色 + * created\_user\_id - 创建者用户 ID -## 验证新的追踪记录 +#### 生成名称跟踪 -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **Langfuse** 的 **查看**，打开配置的项目。 -3. 按运行时间找到新的追踪记录，打开后查看模型 generation 记录或节点 span。 +**用于跟踪对话标题生成** -运行结束后，追踪记录可能需要一段时间才会显示。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generate NameLangFuse Generation/Trace
user\_idmetadata.user_id
generate\_namename
start\_timestartTime
end\_timeendTime（观察记录）
inputsinput
outputsoutput
metadatametadata
+**生成名称跟踪信息** -## 故障排查 +* conversation\_id - 对话 ID +* inputs - 输入数据 +* outputs - 生成的会话名称 +* start\_time - 开始时间 +* end\_time - 结束时间 +* tenant\_id - 租户 ID +* 元数据 + * conversation\_id - 对话 ID + * tenant\_id - 租户 ID - - - 保存配置时会检查项目访问权限。确认已选择 Langfuse 并启用追踪，然后重新运行应用，在同一项目中查找。 +### Langfuse 提示词管理 - 让管理员检查 worker 日志中的数据接收错误，并确认 Langfuse 能通过 `/api/public/ingestion` 接收数据。如果仍找不到新运行的追踪记录，还需检查 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +[Langfuse 提示词管理插件](https://github.com/gao-ai-com/dify-plugin-langfuse)（社区维护）让你可以在 Dify 应用中使用 [Langfuse 中管理和版本化的提示词](https://langfuse.com/docs/prompt-management/get-started)，增强你的大型语言模型应用开发工作流。主要功能包括： - 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +- **获取提示词**：获取在 Langfuse 中管理的特定提示词。 +- **搜索提示词**：使用各种过滤器在 Langfuse 中搜索提示词。 +- **更新提示词**：在 Langfuse 中创建提示词的新版本，并设置标签/标签。 -如需使用 Langfuse 中管理的提示词，参考社区维护的 [Langfuse 提示词管理插件](https://github.com/gao-ai-com/dify-plugin-langfuse)，了解安装和使用方法。 +此集成简化了管理和版本化提示词的过程，有助于更高效的开发和迭代周期。你可以在[这里](https://github.com/gao-ai-com/dify-plugin-langfuse)找到插件和安装说明。 diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx index 2e3d16fd1..58c2f3e53 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-langsmith.mdx @@ -1,73 +1,389 @@ --- title: 集成 LangSmith -sidebarTitle: LangSmith -description: 将 Dify 应用连接至 LangSmith，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-langsmith)。 -## 连接应用 +### LangSmith 简介 -获取一个 [LangSmith API 密钥](https://docs.langchain.com/langsmith/create-account-api-key)，确保它有权读取目标工作空间中的项目并发送追踪数据。确定要使用的项目名称，填写时保持完全一致。 +LangSmith 是一个用于构建生产级 LLM 应用的平台，它用于开发、协作、测试、部署和监控 LLM 应用。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **LangSmith** 的 **配置**，填写连接信息： + +LangSmith [官网介绍](https://www.langchain.com/langsmith) + -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **API Key** | 是 | 有权读取项目和写入追踪数据的密钥。 | -| **项目** | 是 | 项目名称。如果项目不存在，LangSmith 会在收到第一条追踪数据时创建。 | -| **Endpoint** | 否 | 默认为 `https://api.smith.langchain.com`。自定义 API 端点必须使用 HTTPS，并保留所需的路径前缀。 | +### 配置 LangSmith -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 LangSmith 会替换当前选择。 +本章节将指引你注册 LangSmith 并将其集成至 Dify 平台内。 -编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 +#### 1. 注册/登录 [LangSmith](https://www.langchain.com/langsmith) -## Dify 发送的数据 +#### 2. 创建项目 -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +在 LangSmith 内创建项目，登录后在主页点击 **New Project** 创建一个自己的项目，**项目**将用于与 Dify 内的**应用**关联进行数据监测。 -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 + + ![在 LangSmith 内创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/58e20105fcc0771ca2431e8e5dcc42d3.png) + -在 LangSmith 中打开一次模型运行，可查看采集到的输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 +创建完成之后在 Projects 内可以查看该项目。 -### 采集 Agent 调用和内容 + + ![在 LangSmith 内查看已创建项目](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/642c0ff7edfdfe77fba43aa22cc3fa71.png) + - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +#### 3. 创建项目凭据 + +创建项目凭据，在左侧边栏内找到项目设置 **Settings**。 + + + ![项目设置](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/c49a1fc769215193928ff0d880422f89.png) + + +点击 **Create API Key**，创建一个项目凭据。 + + + ![创建一个项目 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/7082286b0d12af4bc0c84d9a3acf8b1b.png) + + +选择 **Personal Access Token** ，用于后续的 API 身份校验。 + + + ![创建一个 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/75a69bd4dd02f0ffc0313589ae12fb36.png) + + +将创建的 API key 复制保存。 + + + ![复制 API Key](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/723e96a13e8f722d6df714b11ffd0bb1.png) + + +#### 4. 将 LangSmith 集成至 Dify 平台 + +在 Dify 应用内配置 LangSmith。打开需要监测的应用，在左侧边菜单内打开 **监测**，点击页面内的 **配置。** + + + ![配置 LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/b6578e410979cdb9da901aedc94a444d.png) + -在应用的追踪设置中，找到 **Agent 数据采集**： +点击配置后，将 **API Key** 和 **项目** 名称粘贴到配置内并保存。密钥必须具备项目读取和追踪写入权限。**Endpoint** 默认为 `https://api.smith.langchain.com`；自定义 API 地址必须使用 HTTPS。 -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 + + ![配置 LangSmith](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/27173b2503ca7241b084f7cbd17cdb4c.png) + + + +配置项目名需要与 LangSmith 内设置的项目一致，若项目不存在，LangSmith 会在收到第一条追踪记录时创建项目，保存配置时不会创建。 + + +成功保存后可以在当前页面查看监测状态。 + + + ![查看配置状态](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/a4e9df6427c7914e1eef6af78d71f408.png) + + +### 在 LangSmith 内查看监测数据 + +配置完成后，Dify 内应用的调试或生产数据可以在 LangSmith 查看监测数据。 + + + ![在 Dify 内调试应用](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/a0e7b21d56ecf9313f1bd48913f0a74b.png) + + + + ![在 LangSmith 内查看应用数据](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/2833b2ffa20927b5328e9624b065beea.png) + + + + ![在 LangSmith 内查看应用数据](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/monitoring/integrate-external-ops-tools/c40e522f1ffe9fc50411dd7feaf937ed.png) + -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +### 监测数据清单 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +#### Workflow /Chatflow Trace 信息 + +**用于追踪 workflow 以及 chatflow** + +| Workflow | LangSmith Chain | +| ---------------------------------------- | -------------------------- | +| workflow_run_id | id | +| user_id | extra.metadata.user_id | +| workflow | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| outputs | outputs | +| 模型 token 消耗（LLM 调用） | outputs.usage_metadata | +| metadata | extra.metadata | +| error | error | +| 会话 ID | extra.metadata.session_id | +| 父 span（如有） | parent\_run\_id | + +**Workflow Trace Info** + +* workflow\_id - Workflow 的唯一标识 +* conversation\_id - 对话 ID +* workflow\_run\_id - 此次运行的 ID +* tenant\_id - 租户 ID +* elapsed\_time - 此次运行耗时 +* status - 运行状态 +* version - Workflow 版本 +* total\_tokens - 此次运行使用的 token 总数 +* file\_list - 处理的文件列表 +* triggered\_from - 触发此次运行的来源 +* workflow\_run\_inputs - 此次运行的输入数据 +* workflow\_run\_outputs - 此次运行的输出数据 +* error - 此次运行中发生的错误 +* query - 运行时使用的查询 +* workflow\_app\_log\_id - Workflow 应用日志 ID +* message\_id - 关联的消息 ID +* start\_time - 运行开始时间 +* end\_time - 运行结束时间 +* workflow node executions - workflow 节点运行信息 +* Metadata + * workflow\_id - Workflow 的唯一标识 + * conversation\_id - 对话 ID + * workflow\_run\_id - 此次运行的 ID + * tenant\_id - 租户 ID + * elapsed\_time - 此次运行耗时 + * status - 运行状态 + * version - Workflow 版本 + * total\_tokens - 此次运行使用的 token 总数 + * file\_list - 处理的文件列表 + * triggered\_from - 触发来源 + +#### Message Trace 信息 + +**用于追踪 llm 对话相关** + +| Chat | LangSmith Chain / LLM | +| -------------------------------- | -------------------------- | +| message\_id | id | +| end\_user\_session\_id | extra.metadata.end_user_session_id | +| message | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| outputs | outputs | +| 模型 token 消耗（LLM 调用） | outputs.usage_metadata | +| metadata | extra.metadata | +| error | error | +| 会话 ID | extra.metadata.session_id | + +**Message Trace Info** + +* message\_id - 消息 ID +* message\_data - 消息数据 +* end\_user\_session\_id - 用户的 session\_id +* conversation\_model - 对话模式 +* message\_tokens - 消息中的令牌数 +* answer\_tokens - 回答中的令牌数 +* total\_tokens - 消息和回答中的总令牌数 +* error - 错误信息 +* inputs - 输入数据 +* outputs - 输出数据 +* file\_list - 处理的文件列表 +* start\_time - 开始时间 +* end\_time - 结束时间 +* conversation\_mode - 对话模式 +* Metadata + * conversation\_id - 消息所属对话的 ID + * ls\_provider - 模型提供者 + * ls\_model\_name - 模型 ID + * status - 消息状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户的 ID + * agent\_based - 是否基于代理 + * workflow\_run\_id - 工作流运行 ID + * from\_source - 消息来源 + * message\_id - 消息 ID + +#### Moderation Trace 信息 + +**用于追踪对话审查** + +| Moderation | LangSmith Tool | +| ------------- | --------------- | +| user\_id | extra.metadata.user_id | +| moderation | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| action, flagged | outputs | +| metadata | extra.metadata | +| message\_id | parent\_run\_id | + +**Message Trace Info** + +* message\_id - 消息 ID +* user\_id: 用户 id +* workflow\_app\_log\_id workflow\_app\_log\_id +* inputs - 审查的输入数据 +* message\_data - 消息数据 +* flagged - 是否被标记为需要注意的内容 +* action - 执行的具体行动 +* preset\_response - 预设响应 +* start\_time - 审查开始时间 +* end\_time - 审查结束时间 +* Metadata + * message\_id - 消息 ID + * action - 执行的具体行动 + * preset\_response - 预设响应 + +#### Suggested Question Trace 信息 + +**用于追踪建议问题** + +| Suggested Question | LangSmith Tool | +| ---------------------- | --------------- | +| user\_id | extra.metadata.user_id | +| suggested\_question | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| suggested_question | outputs | +| metadata | extra.metadata | +| message\_id | parent\_run\_id | + +**Message Trace Info** + +* message\_id - 消息 ID +* message\_data - 消息数据 +* inputs - 输入的内容 +* outputs - 输出的内容 +* start\_time - 开始时间 +* end\_time - 结束时间 +* total\_tokens - 令牌数量 +* status - 消息状态 +* error - 错误信息 +* from\_account\_id - 发送账户的 ID +* agent\_based - 是否基于代理 +* from\_source - 消息来源 +* model\_provider - 模型提供者 +* model\_id - 模型 ID +* suggested\_question - 建议的问题 +* level - 状态级别 +* status\_message - 状态信息 +* Metadata + * message\_id - 消息 ID + * ls\_provider - 模型提供者 + * ls\_model\_name - 模型 ID + * status - 消息状态 + * from\_end\_user\_id - 发送用户的 ID + * from\_account\_id - 发送账户的 ID + * workflow\_run\_id - 工作流运行 ID + * from\_source - 消息来源 + +#### Dataset Retrieval Trace 信息 + +**用于追踪知识库检索** + +| Dataset Retrieval | LangSmith Retriever | +| --------------------- | ------------------- | +| user\_id | extra.metadata.user_id | +| dataset\_retrieval | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| documents | outputs | +| metadata | extra.metadata | +| message\_id | parent\_run\_id | + +**Dataset Retrieval Trace Info** + +* message\_id - 消息 ID +* inputs - 输入内容 +* documents - 文档数据 +* start\_time - 开始时间 +* end\_time - 结束时间 +* message\_data - 消息数据 +* Metadata + * message\_id 消息 ID + * ls\_provider 模型提供者 + * ls\_model\_name 模型 ID + * status 消息状态 + * from\_end\_user\_id 发送用户的 ID + * from\_account\_id 发送账户的 ID + * agent\_based 是否基于代理 + * workflow\_run\_id 工作流运行 ID + * from\_source 消息来源 + +#### Tool Trace 信息 + +**用于追踪工具调用** -## 验证新的追踪记录 +| Tool | LangSmith Tool | +| --------------------- | --------------- | +| user\_id | extra.metadata.user_id | +| tool\_name | name | +| start\_time | start\_time | +| end\_time | end\_time | +| tool_inputs | inputs | +| tool_outputs | outputs | +| metadata | extra.metadata | +| message\_id | parent\_run\_id | -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **LangSmith** 的 **查看**。 -3. 在配置的项目中，按运行时间找到新的运行记录，查看其中的子运行。 +**Tool Trace Info** -运行结束后，追踪记录可能需要一段时间才会显示。 +* message\_id 消息 ID +* tool\_name 工具名称 +* start\_time 开始时间 +* end\_time 结束时间 +* tool\_inputs 工具输入 +* tool\_outputs 工具输出 +* message\_data 消息数据 +* error 错误信息，如果存在 +* inputs 消息的输入内容 +* outputs 消息的回答内容 +* tool\_config 工具配置 +* time\_cost 时间成本 +* tool\_parameters 工具参数 +* file\_url 关联文件的 URL +* Metadata + * message\_id 消息 ID + * tool\_name 工具名称 + * tool\_inputs 工具输入 + * tool\_outputs 工具输出 + * tool\_config 工具配置 + * time\_cost 时间成本 + * error 错误信息 + * tool\_parameters 工具参数 + * message\_file\_id 消息文件 ID + * created\_by\_role 创建者角色 + * created\_user\_id 创建者用户 ID -如果第一条追踪数据到达后，点击 **查看** 仍打开项目列表，重新保存配置即可更新项目链接。 +#### Generate Name Trace 信息 -## 故障排查 +**用于追踪会话标题生成** - - - 保存配置时会检查项目访问权限；新项目在收到第一条追踪数据时才会创建。确认已选择 LangSmith 并启用追踪，然后重新运行应用，按配置中填写的完整项目名称查找。 +| Generate Name | LangSmith Tool | +| ----------------- | -------------- | +| user\_id | extra.metadata.user_id | +| generate\_name | name | +| start\_time | start\_time | +| end\_time | end\_time | +| inputs | inputs | +| outputs | outputs | +| metadata | extra.metadata | - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +**Generate Name Trace Info** - 使用内网端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +* conversation\_id 对话 ID +* inputs 输入数据 +* outputs 生成的会话名称 +* start\_time 开始时间 +* end\_time 结束时间 +* tenant\_id 租户 ID +* Metadata + * conversation\_id 对话 ID + * tenant\_id 租户 ID diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx index c62181e63..33f62cef4 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-opik.mdx @@ -1,72 +1,349 @@ --- title: 集成 Opik -sidebarTitle: Opik -description: 将 Dify 应用连接至 Opik，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-opik)。 -## 连接应用 +## Opik 简介 -获取托管版 Opik 的 API 密钥，或使用自建 Opik 实例。账户设置方法详见 [Opik 的 Dify 集成指南](https://www.comet.com/docs/opik/integrations/dify)。使用自建服务器上的指定工作空间时，向管理员确认工作空间名称。 +Opik 是一个开源的 LLM 评估平台，用于评估、测试和监控大型语言模型（LLM）应用。它由 Comet 开发，旨在促进对基于 LLM 的应用进行更直观的协作、测试和监控。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Opik** 的 **配置**，填写连接信息： + +如需了解更多详情，请参考 [Opik](https://www.comet.com/site/products/opik/)。 + -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **API Key** | 托管版 Opik 必填 | 账户的 API 密钥。仅当服务器未启用认证时可留空。 | -| **项目** | 否 | 项目名称；Opik 会在收到第一条追踪数据时创建项目。留空时，Dify 使用 `Default Project`。 | -| **Workspace** | 否 | 已有的工作空间。留空时，Dify 使用账户默认工作空间；对于未启用认证的开源服务器，则使用 `default`。 | -| **Url** | 否 | 默认为 `https://www.comet.com/opik/api/`。自定义 HTTP(S) URL 必须以 `/api/` 结尾。 | +--- -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Opik 会替换当前选择。 +## 开始配置 Opik -编辑配置时，已保存的凭据不会显示。如果 **Url** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 +使用托管版 Opik 时，按以下步骤注册账户并获取 API 密钥。如果自部署实例未启用身份验证，**API Key** 可留空。 -## Dify 发送的数据 +### 1. 注册/登录 [Opik](https://www.comet.com/signup?from=llm) -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +### 2. 获取 Opik API 密钥 -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 +从右上角的用户菜单中获取 Opik API 密钥。点击 **API Key**，然后点击 API Key 进行复制： -在 Opik 中打开一个 LLM span，可查看采集到的模型调用输入和输出。如果有 token 数量和美元费用数据，会显示在对应的用量和费用字段中。 + + ![](https://assets-docs.dify.ai/2025/01/a66603f01e4ffaa593a8b78fcf3f8204.png) + -### 采集 Agent 调用和内容 +### 3. 集成 Opik 与 Dify - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +在 Dify 应用中配置 Opik。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 + + + ![](https://assets-docs.dify.ai/2025/01/9d52a244e3b6cef1874ee838cd976111.png) + + +点击配置后，按需填写 **API Key**，并输入 **项目** 名称。项目留空时使用 `Default Project`；新项目在收到第一条追踪记录时创建。**Workspace** 可留空，使用账户的默认工作区。自部署 Opik 需将 **Url** 设为以 `/api/` 结尾的 API 基础 URL（默认为 `https://www.comet.com/opik/api/`），然后保存。 + + + ![](https://assets-docs.dify.ai/2025/01/7f4c436e2dc9fe94a3ed49219bb3360c.png) + + +成功保存后，你可以在当前页面查看监控状态。 + +## 查看监控数据 + +配置完成后，你可以照常调试或使用 Dify 应用。新的运行记录可在 Opik 中查看，启用前的使用历史不会补发。 + + + ![](https://assets-docs.dify.ai/2025/01/a1c5aa80325e6d0223d48a178393baec.png) + + +当你切换到 Opik 时，可以在仪表板中查看 Dify 应用的详细操作日志。 -在应用的追踪设置中，找到 **Agent 数据采集**： + + ![](https://assets-docs.dify.ai/2025/01/09601d45eaf8ed90a4dfb07c34de36ff.png) + -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 +通过 Opik 的详细 LLM 操作日志将帮助你优化 Dify 应用的性能。 + + + ![](https://assets-docs.dify.ai/2025/01/708533b4fc616f852b5601fe602e3ef5.png) + -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +## 监控数据列表 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +### **Workflow/Chatflow 追踪信息** + +**用于追踪 Workflow 和 Chatflow** + +| 工作流 | Opik 追踪 | +| ---------------------------------- | -------------------------- | +| workflow_run_id | id | +| user_id | metadata.user_id | +| workflow | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| outputs | output | +| 模型 token 消耗（LLM 调用） | usage | +| metadata | metadata | +| error | error_info | +| 会话 ID | thread_id（追踪记录） | + +**工作流追踪信息** + +- workflow_id - 工作流唯一标识符 +- conversation_id - 对话 ID +- workflow_run_id - 当前运行的 ID +- tenant_id - 租户 ID +- elapsed_time - 当前运行所用时间 +- status - 运行状态 +- version - 工作流版本 +- total_tokens - 当前运行使用的总令牌数 +- file_list - 处理的文件列表 +- triggered_from - 触发当前运行的来源 +- workflow_run_inputs - 当前运行的输入数据 +- workflow_run_outputs - 当前运行的输出数据 +- error - 当前运行期间遇到的错误 +- query - 运行期间使用的查询 +- workflow_app_log_id - Workflow 应用日志 ID +- message_id - 关联的消息 ID +- start_time - 运行开始时间 +- end_time - 运行结束时间 +- workflow node executions - 工作流节点执行信息 +- 元数据 + - workflow_id - 工作流唯一标识符 + - conversation_id - 对话 ID + - workflow_run_id - 当前运行的 ID + - tenant_id - 租户 ID + - elapsed_time - 当前运行所用时间 + - status - 运行状态 + - version - 工作流版本 + - total_tokens - 当前运行使用的总令牌数 + - file_list - 处理的文件列表 + - triggered_from - 触发当前运行的来源 + +#### **消息追踪信息** + +**用于追踪 LLM 相关对话** + +| 聊天 | Opik Trace | +| ------------------------------- | --------------------------- | +| message_id | id | +| end_user_session_id | metadata.end_user_session_id | +| message | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| outputs | output | +| 模型 token 消耗（LLM 调用） | usage | +| metadata | metadata | +| 会话 ID | thread_id（追踪记录） | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- end_user_session_id - 用户会话 ID +- conversation_model - 对话模式 +- message_tokens - 消息中的令牌数 +- answer_tokens - 答案中的令牌数 +- total_tokens - 消息和答案中的总令牌数 +- error - 错误信息 +- inputs - 输入数据 +- outputs - 输出数据 +- file_list - 处理的文件列表 +- start_time - 开始时间 +- end_time - 结束时间 +- conversation_mode - 对话模式 +- 元数据 + - conversation_id - 对话 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 消息是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **审核追踪信息** + +**用于追踪对话审核** + +| 审核 | Opik Tool | +| -------------- | ----------------- | +| user_id | metadata.user_id | +| "moderation" | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| action, flagged | output | +| metadata | metadata | + +**审核追踪信息** + +- message_id - 消息 ID +- user_id - 用户 ID +- workflow_app_log_id - Workflow 应用日志 ID +- inputs - 审核输入数据 +- message_data - 消息数据 +- flagged - 内容是否被标记需要注意 +- action - 采取的具体行动 +- preset_response - 预设响应 +- start_time - 审核开始时间 +- end_time - 审核结束时间 +- 元数据 + - message_id - 消息 ID + - action - 采取的具体行动 + - preset_response - 预设响应 + +#### **建议问题追踪信息** + +**用于追踪建议问题** + +| 建议问题 | Opik Trace | +| --------------------- | ----------------- | +| user_id | metadata.user_id | +| "suggested_question" | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| suggested_question | output | +| metadata | metadata | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- inputs - 输入内容 +- outputs - 输出内容 +- start_time - 开始时间 +- end_time - 结束时间 +- total_tokens - 令牌数量 +- status - 消息状态 +- error - 错误信息 +- from_account_id - 发送账户的 ID +- agent_based - 是否基于代理 +- from_source - 消息来源 +- model_provider - 模型供应商 +- model_id - 模型 ID +- suggested_question - 建议问题 +- level - 状态级别 +- status_message - 状态消息 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **数据集检索追踪信息** + +**用于追踪知识库检索** + +| 数据集检索 | Opik Retriever | +| ------------------- | ----------------- | +| user_id | metadata.user_id | +| "dataset_retrieval" | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| documents | output | +| metadata | metadata | +| message_id | trace_id | + +**数据集检索追踪信息** + +- message_id - 消息 ID +- inputs - 输入内容 +- documents - 文档数据 +- start_time - 开始时间 +- end_time - 结束时间 +- message_data - 消息数据 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **工具追踪信息** + +**用于追踪工具调用** + +| 工具 | Opik Tool | +| -------------------- | ----------------- | +| user_id | metadata.user_id | +| tool_name | name | +| start_time | start_time | +| end_time | end_time | +| tool_inputs | input | +| tool_outputs | output | +| metadata | metadata | -## 验证新的追踪记录 +#### **工具追踪信息** -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **Opik** 的 **查看**。如果链接打开控制台，选择配置的工作空间和项目。 -3. 按运行时间找到新的追踪记录，打开后查看其中的 span。 +- message_id - 消息 ID +- tool_name - 工具名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tool_inputs - 工具输入 +- tool_outputs - 工具输出 +- message_data - 消息数据 +- error - 错误信息（如果有） +- inputs - 消息的输入 +- outputs - 消息的输出 +- tool_config - 工具配置 +- time_cost - 时间消耗 +- tool_parameters - 工具参数 +- file_url - 关联文件的 URL +- 元数据 + - message_id - 消息 ID + - tool_name - 工具名称 + - tool_inputs - 工具输入 + - tool_outputs - 工具输出 + - tool_config - 工具配置 + - time_cost - 时间消耗 + - error - 错误信息（如果有） + - tool_parameters - 工具参数 + - message_file_id - 消息文件 ID + - created_by_role - 创建者角色 + - created_user_id - 创建者用户 ID -运行结束后，追踪记录可能需要一段时间才会显示。 +#### **生成名称追踪信息** -## 故障排查 +**用于追踪对话标题生成** - - - 保存配置时会检查工作空间访问权限；Opik 在收到第一条追踪数据时创建项目。确认已选择 Opik 并启用追踪。在 Opik 中打开配置的工作空间和项目，然后重新运行应用。 +| 生成名称 | Opik Tool | +| ---------------------------- | ----------------- | +| user_id | metadata.user_id | +| generate_name | name | +| start_time | start_time | +| end_time | end_time | +| inputs | input | +| outputs | output | +| metadata | metadata | - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +**生成名称追踪信息** - 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +- conversation_id - 对话 ID +- inputs - 输入数据 +- outputs - 生成的对话名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tenant_id - 租户 ID +- 元数据 + - conversation_id - 对话 ID + - tenant_id - 租户 ID diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx index 1fcf075d7..e3b2059d7 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-phoenix.mdx @@ -1,75 +1,383 @@ --- title: 集成 Phoenix -sidebarTitle: Phoenix -description: 将 Dify 应用连接至 Phoenix，验证新的追踪记录，并选择要发送的 Agent 数据 --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-phoenix)。 -## 连接应用 +### Phoenix 简介 -选择 Dify 服务能访问的 Phoenix 实例，自部署或 Phoenix Cloud 均可。如果实例启用了认证，获取一个有权读取项目并发送追踪数据的 [API 密钥](https://arize.com/docs/phoenix/settings/api-keys)。如需连接 Arize，参考 [Arize 集成](/zh/self-host/use-dify/monitor/integrations/integrate-arize)。 +[Arize Phoenix](https://arize.com/phoenix/) 是 [Arize AI](https://arize.com/?utm_source=dify-docs&utm_medium=partner&utm_campaign=partner-docs&utm_content=integrate-phoenix-self-host) 推出的开源平台，基于 OpenTelemetry 构建，为 LLM 工作流和 Agent 提供可观测性、评估、提示工程和实验能力。 -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Phoenix** 的 **配置**，填写连接信息： +开发阶段可在本地运行 Phoenix，也可在自有基础设施上以单容器方式自部署，或使用 Arize 托管的 [Phoenix Cloud](#配置-phoenix-cloud)。 -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **API Key** | 启用认证时必填 | 实例或 Phoenix Cloud 空间的密钥。服务器未启用认证时留空。 | -| **项目** | 是 | 目标项目名称。 | -| **Endpoint** | 否 | Phoenix 基础 URL。将默认值 `https://app.phoenix.arize.com` 替换为 Cloud 空间或自部署实例的 URL，并保留路径前缀。 | +如需面向生产环境团队、AI 原生公司和企业的全功能平台，可改用 [Arize 集成](/zh/self-host/use-dify/monitor/integrations/integrate-arize) 接入 [Arize AX](https://arize.com/products/ax/)。 -使用 Phoenix Cloud 时，复制空间地址，例如 `https://app.phoenix.arize.com/s/`。获取位置详见 [查找 Phoenix 端点](https://arize.com/docs/phoenix/learn/resources/faqs/what-is-my-phoenix-endpoint)。填写基础 URL 时不要包含 `/v1/traces`，Dify 会自动添加该路径。 +追踪数据接入后，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [LLM 评估指南](https://arize.com/resources/llm-evaluation/)，了解如何用追踪数据调试故障、评估 Agent 行为、监控模型质量。 -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Phoenix 会替换当前选择。 +### 配置 Phoenix -编辑配置时，已保存的凭据不会显示。如果 **Endpoint** 不变，将凭据留空即可保留原值；如果更改目标地址，则需重新填写凭据。 +本章节将指引你注册 Phoenix 并将其集成至 Dify 平台内。 -## Dify 发送的数据 +如果自部署的 Phoenix 实例未启用身份验证，可跳过以下账户和 API 密钥步骤，并将 **API Key** 留空。 -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +#### 1. 注册/登录 [Phoenix](https://app.arize.com/auth/phoenix/signup) -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 +### 2. 获取 Phoenix API 密钥 -在 Phoenix 中打开一个模型 span，可查看采集到的输入和输出，以及已记录的 token 数量。Dify 不会填充 Phoenix 的内置费用字段。 +从右上角的用户菜单中获取 Phoenix API 密钥。点击 **API Key**，然后点击 API Key 进行复制： -### 采集 Agent 调用和内容 + + ![](https://i.ibb.co/pB1W0pk8/dify-docs-phoenix-api-key.png) + - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +### 3. 集成 Phoenix 与 Dify + +在 Dify 应用中配置 Phoenix。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 + + + ![](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +点击配置后，输入 **项目** 名称；若启用了身份验证，还需填写 **API Key**。在 **Endpoint** 中填写 Phoenix 实例的基础 URL，然后保存。不要添加 `/v1/traces`，Dify 会自动补全数据接入路径。 + + + ![](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + + +成功保存后，你可以在当前页面查看监控状态。 + + + ![](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + + +### 配置 Phoenix Cloud + +本章节将指引你注册 Phoenix Cloud 并将其集成至 Dify 平台内。 + +#### 1. 注册/登录 [Phoenix Cloud](https://app.arize.com/auth/phoenix/signup) + +### 2. 创建你的 Phoenix 空间 + +你可以在右上角的用户菜单中创建 Phoenix 空间。点击 创建空间，然后为你的空间提供一个唯一的 URL 标识符： + + + ![](https://i.ibb.co/7JYPzZBf/dify-docs-phoenix-cloud-create-space.png) + -在应用的追踪设置中，找到 **Agent 数据采集**： +保存成功后，你可以在概览页面查看空间的状态。 -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 + + ![](https://i.ibb.co/Z6RqMhhq/dify-docs-phoenix-cloud-space-overview.png) + + +### 3. 创建你的 Phoenix API 密钥 + +启动空间后，你可以在左下角的用户菜单中点击 设置 来创建 Phoenix API 密钥。点击 系统密钥，然后为你的 API 密钥命名： + + + ![](https://i.ibb.co/SXMyX9K3/dify-docs-phoenix-cloud-api-key.png) + + +### 4. 集成 Phoenix Cloud 与 Dify + +在 Dify 应用中配置 Phoenix。打开需要监控的应用，在侧边菜单中打开 **监控**，并在页面上选择 **追踪应用性能**。 + + + ![](https://i.ibb.co/gMmXxfhQ/dify-docs-phoenix-in-use.png) + + +点击配置后，粘贴 **API Key** 和 **项目** 名称，并在 **Endpoint** 中填写完整的 Phoenix Cloud 空间 URL（例如 `https://app.phoenix.arize.com/s/`），然后保存。 + + + ![](https://i.ibb.co/jv6QFbp7/dify-docs-phoenix-config.png) + + +成功保存后，你可以在当前页面查看监控状态。 + + + ![](https://i.ibb.co/HTJsj9x2/dify-docs-phoenix-in-service.png) + -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +## 监控数据列表 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +### **Workflow/Chatflow 追踪信息** + +**用于追踪 Workflow 和 Chatflow** + +| 工作流 | Phoenix 追踪 | +| ---------------------------------- | -------------------------- | +| workflow_run_id | span_id | +| user_id | metadata.user_id | +| workflow | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| 模型 token 消耗（LLM 调用） | llm.token_count.prompt / completion / total | +| metadata | metadata | +| error | status.code / status.message | +| 会话 ID | session.id | + +**工作流追踪信息** + +- workflow_id - 工作流唯一标识符 +- conversation_id - 对话 ID +- workflow_run_id - 当前运行的 ID +- tenant_id - 租户 ID +- elapsed_time - 当前运行所用时间 +- status - 运行状态 +- version - 工作流版本 +- total_tokens - 当前运行使用的总令牌数 +- file_list - 处理的文件列表 +- triggered_from - 触发当前运行的来源 +- workflow_run_inputs - 当前运行的输入数据 +- workflow_run_outputs - 当前运行的输出数据 +- error - 当前运行期间遇到的错误 +- query - 运行期间使用的查询 +- workflow_app_log_id - Workflow 应用日志 ID +- message_id - 关联的消息 ID +- start_time - 运行开始时间 +- end_time - 运行结束时间 +- workflow node executions - 工作流节点执行信息 +- 元数据 + - workflow_id - 工作流唯一标识符 + - conversation_id - 对话 ID + - workflow_run_id - 当前运行的 ID + - tenant_id - 租户 ID + - elapsed_time - 当前运行所用时间 + - status - 运行状态 + - version - 工作流版本 + - total_tokens - 当前运行使用的总令牌数 + - file_list - 处理的文件列表 + - triggered_from - 触发当前运行的来源 + +#### **消息追踪信息** + +**用于追踪 LLM 相关对话** + +| 聊天 | Phoenix Trace | +| ------------------------------- | --------------------------- | +| message_id | span_id | +| end_user_session_id | metadata.end_user_session_id | +| message | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| 模型 token 消耗（LLM 调用） | llm.token_count.prompt / completion / total | +| metadata | metadata | +| 会话 ID | session.id | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- end_user_session_id - 用户会话 ID +- conversation_model - 对话模式 +- message_tokens - 消息中的令牌数 +- answer_tokens - 答案中的令牌数 +- total_tokens - 消息和答案中的总令牌数 +- error - 错误信息 +- inputs - 输入数据 +- outputs - 输出数据 +- file_list - 处理的文件列表 +- start_time - 开始时间 +- end_time - 结束时间 +- conversation_mode - 对话模式 +- 元数据 + - conversation_id - 对话 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 消息是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **审核追踪信息** + +**用于追踪对话审核** + +| 审核 | Phoenix Tool | +| -------------- | ----------------- | +| user_id | metadata.user_id | +| "moderation" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| action, flagged | output.value | +| metadata | metadata | + +**审核追踪信息** + +- message_id - 消息 ID +- user_id - 用户 ID +- workflow_app_log_id - Workflow 应用日志 ID +- inputs - 审核输入数据 +- message_data - 消息数据 +- flagged - 内容是否被标记需要注意 +- action - 采取的具体行动 +- preset_response - 预设响应 +- start_time - 审核开始时间 +- end_time - 审核结束时间 +- 元数据 + - message_id - 消息 ID + - action - 采取的具体行动 + - preset_response - 预设响应 + +#### **建议问题追踪信息** + +**用于追踪建议问题** + +| 建议问题 | Phoenix Trace | +| --------------------- | ----------------- | +| user_id | metadata.user_id | +| "suggested_question" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| suggested_question | output.value | +| metadata | metadata | + +**消息追踪信息** + +- message_id - 消息 ID +- message_data - 消息数据 +- inputs - 输入内容 +- outputs - 输出内容 +- start_time - 开始时间 +- end_time - 结束时间 +- total_tokens - 令牌数量 +- status - 消息状态 +- error - 错误信息 +- from_account_id - 发送账户的 ID +- agent_based - 是否基于代理 +- from_source - 消息来源 +- model_provider - 模型供应商 +- model_id - 模型 ID +- suggested_question - 建议问题 +- level - 状态级别 +- status_message - 状态消息 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **数据集检索追踪信息** + +**用于追踪知识库检索** + +| 数据集检索 | Phoenix Retriever | +| ------------------- | ----------------- | +| user_id | metadata.user_id | +| "dataset_retrieval" | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| documents | output.value | +| metadata | metadata | +| message_id | parent_span_id | + +**数据集检索追踪信息** + +- message_id - 消息 ID +- inputs - 输入内容 +- documents - 文档数据 +- start_time - 开始时间 +- end_time - 结束时间 +- message_data - 消息数据 +- 元数据 + - message_id - 消息 ID + - ls_provider - 模型供应商 + - ls_model_name - 模型 ID + - status - 消息状态 + - from_end_user_id - 发送用户的 ID + - from_account_id - 发送账户的 ID + - agent_based - 是否基于代理 + - workflow_run_id - 工作流运行 ID + - from_source - 消息来源 + +#### **工具追踪信息** + +**用于追踪工具调用** -## 验证新的追踪记录 +| 工具 | Phoenix Tool | +| -------------------- | ----------------- | +| user_id | metadata.user_id | +| tool_name | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| tool_inputs | input.value | +| tool_outputs | output.value | +| metadata | metadata | -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **Phoenix** 的 **查看**，打开配置的项目。 -3. 按运行时间找到新的追踪记录，打开后查看子 span。 +#### **工具追踪信息** -运行结束后，追踪记录可能需要一段时间才会显示。 +- message_id - 消息 ID +- tool_name - 工具名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tool_inputs - 工具输入 +- tool_outputs - 工具输出 +- message_data - 消息数据 +- error - 错误信息（如果有） +- inputs - 消息的输入 +- outputs - 消息的输出 +- tool_config - 工具配置 +- time_cost - 时间消耗 +- tool_parameters - 工具参数 +- file_url - 关联文件的 URL +- 元数据 + - message_id - 消息 ID + - tool_name - 工具名称 + - tool_inputs - 工具输入 + - tool_outputs - 工具输出 + - tool_config - 工具配置 + - time_cost - 时间消耗 + - error - 错误信息（如果有） + - tool_parameters - 工具参数 + - message_file_id - 消息文件 ID + - created_by_role - 创建者角色 + - created_user_id - 创建者用户 ID -## 故障排查 +#### **生成名称追踪信息** - - - 保存配置时会确认项目读取权限，不会发送追踪数据。确认已选择 Phoenix 并启用追踪，然后重新运行应用，在配置的项目中查找。 +**用于追踪对话标题生成** - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +| 生成名称 | Phoenix Tool | +| ---------------------------- | ----------------- | +| user_id | metadata.user_id | +| generate_name | name | +| start_time | start_time_unix_nano | +| end_time | end_time_unix_nano | +| inputs | input.value | +| outputs | output.value | +| metadata | metadata | - 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +**生成名称追踪信息** -评估已采集的追踪数据时，可参考 Arize 的 [Agent 评估指南](https://arize.com/guides/ai-agent-handbook/agent-evaluation/) 和 [大语言模型评估指南](https://arize.com/resources/llm-evaluation/)。 +- conversation_id - 对话 ID +- inputs - 输入数据 +- outputs - 生成的对话名称 +- start_time - 开始时间 +- end_time - 结束时间 +- tenant_id - 租户 ID +- 元数据 + - conversation_id - 对话 ID + - tenant_id - 租户 ID diff --git a/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx b/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx index 70d3d35b0..997d121bc 100644 --- a/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx +++ b/zh/self-host/use-dify/monitor/integrations/integrate-weave.mdx @@ -1,75 +1,349 @@ --- title: 集成 W&B Weave -sidebarTitle: W&B Weave -description: 将 Dify 应用的追踪数据发送至 W&B Weave，实现大语言模型可观测性 +description: 通过 W&B Weave 实现 Dify 应用的 LLM 可观测性，将追踪数据发送至 W&B Weave --- > 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/monitor/integrations/integrate-weave)。 -## 连接应用 + + **前提条件**：Dify v1.3.1 或更高版本。 + -配置 Dify 前，先创建一个 [W&B 项目](https://docs.wandb.ai/models/track/project-page#create-a-project)，确保 [API 密钥](https://wandb.ai/authorize) 有该项目的写入权限。团队项目的 **Entity** 填写所属团队。 +### 什么是 W&B Weave -在 Dify 应用中，打开 **监测**（Agent 应用中为 **监控**）> **追踪应用性能**。点击 **Weave** 的 **配置**，填写连接信息： +Weights & Biases (W&B) Weave 是一个用于跟踪、实验、评估、部署和改进基于 LLM 的应用的框架。Weave 专为灵活性和可扩展性而设计，支持 LLM 应用开发工作流的每个阶段。 -| 字段 | 是否必填 | 填写内容 | -|:------|:---------|:------| -| **API Key** | 是 | W&B API 密钥。 | -| **项目** | 是 | 已存在且有写入权限的项目。也可在此填写 `entity/project`，将 **Entity** 留空。 | -| **Entity** | 否 | W&B 团队或用户。留空时，Dify 使用 API 密钥对应的默认 entity。 | -| **Endpoint** | 否 | Weave 追踪服务器地址。默认为 `https://trace.wandb.ai`，必须使用 HTTPS。 | -| **Host** | 否 | W&B API 服务器地址。默认为 `https://api.wandb.ai`，支持 HTTP(S)。 | + + 更多详情，请参考 [Weave](https://docs.wandb.ai/weave)。 + -使用自定义部署时，向管理员获取追踪服务器的 **Endpoint** 和 W&B API 的 **Host**，并保留其提供的路径前缀。 +### 如何配置 Weave -确认 [Dify 发送的数据](#dify-发送的数据) 后，点击 **保存并启用**。每个应用只能启用一个追踪服务；选择 Weave 会替换当前选择。 +#### 1. 注册/登录 -编辑配置时，已保存的凭据不会显示。如果 **Host** 和 **Endpoint** 均不变，将凭据留空即可保留原值；如果更改任一地址，则需重新填写凭据。 +前往 [W&B Weave](https://wandb.ai/signup) 注册/登录。创建一个 Weights & Biases (W&B) 账户，并在[此处](https://wandb.ai/authorize)复制 API 密钥。 -## Dify 发送的数据 +#### 2. 将 W&B Weave 与 Dify 集成 -一条追踪记录包含一次应用执行中的各项操作及其耗时，每个操作称为一个 **span**。每个 span 包含状态和错误信息。Dify 还会发送采集到的输入和输出、模型用量，以及消息、工作流和节点的 ID 等元数据。 +在 Dify 应用中配置 Weave。打开需要监控的应用，在侧边菜单中打开 **监控**，在页面上选择 **跟踪应用性能**。 -在 Workflow 应用的追踪记录中，可查看各节点的 span，包括循环和迭代分组。聊天追踪记录会在消息下展示模型调用。Chatflow 应用的追踪记录则在消息下展示工作流。 + + ![在 Dify 应用中配置 Weave](https://assets-docs.dify.ai/2025/04/c33e8fda75ee9052ed23c8690e314862.png) + -在 Weave 中打开一次模型调用，可查看采集到的输入和输出。如果有 token 数量数据，会按模型显示在该调用的用量信息中。Dify 不会填充 Weave 的内置费用字段。 +点击配置后，粘贴 **API Key** 和已存在且可写的 **项目** 名称，并按需指定 **W&B 实体**。实体留空时，Dify 使用 API 密钥的默认实体，该实体也可能是团队。然后保存配置。 -### 采集 Agent 调用和内容 + + ![](https://assets-docs.dify.ai/2025/04/60bce1ae7b883825b13526d172ae0073.png) + - -Agent 应用和 [新 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 默认关闭追踪。让部署管理员同时设置 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。设置位置详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - +成功保存后，你可以在当前页面查看监控状态。 + + + ![成功保存后，你可以在当前页面查看监控状态](https://assets-docs.dify.ai/2025/04/9486cee7bbb61f069842c9ea860e679c.png) + + +### 在 Weave 中查看监控数据 + +配置完成后，Dify 内应用的调试或生产数据可以在 Weave 中进行监控。 -在应用的追踪设置中，找到 **Agent 数据采集**： + + ![](https://assets-docs.dify.ai/2025/04/a1c5aa80325e6d0223d48a178393baec.png) + -- **采集 Agent 内部过程**：调试 Agent 的决策时，保持开启可查看其内部的模型和工具调用。关闭后不再采集这些内部调用，但仍保留 Agent 运行或工作流节点本身。 -- **采集内容**：仅在需要向监控服务发送这些运行的输入和输出时开启。关闭后仍可查看耗时、token 信息和状态。 +当你切换到 Weave 时，可以在仪表板中查看 Dify 应用的详细操作日志。 + + + ![](https://assets-docs.dify.ai/2025/04/2cb04027c00b606029fcc26af2801bfe.png) + + +通过 Weave 获取的详细 LLM 操作日志将帮助你优化 Dify 应用的性能。 -这些设置适用于 Agent 应用，以及包含新 Agent 节点的 Workflow 或 Chatflow 应用。在这些工作流中，**采集内容** 也控制其他节点的输入和输出。其他应用仍可能发送输入和输出；如果不能向监控服务发送这些内容，应保持追踪关闭。 +保存配置并启用追踪后，重新运行应用，在监控服务中确认是否出现新的追踪记录。追踪数据会异步发送，仅保存配置不能确认追踪数据已送达。 + +对于 Agent 应用以及使用 [新版 Agent 节点](/zh/self-host/use-dify/nodes/agent#new-agent) 的工作流，需要在部署中同时启用 `OPS_AGENT_TRACE_ENABLED=true` 和 `DIFY_AGENT_APPLICATION_TRACING_ENABLED=true`。详见 [环境变量](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。这些应用的 **采集内容** 默认关闭，该设置控制整个工作流的输入和输出。其他应用仍可能发送输入和输出。 -新 Agent 节点使用所在 Workflow 或 Chatflow 应用的追踪设置。工作流工具内部的 Agent 调用不会包含在父级 Agent 的追踪记录中。 +### 监控数据列表 + +Dify 会按父子层级导出执行操作：消息包含 `llm` 调用，Chatflow 消息包含工作流及其节点操作。下表中的追踪 ID 和 span ID 由 Dify 派生生成，并非直接复制数据库 ID。只有模型调用会填充监控服务的原生 token 用量字段。 + +以下明细列出 Dify 的源记录和元数据。实际导出时仅发送相关且可用的值，不会完整发送原始记录。 + +#### **Workflow/Chatflow 追踪信息** + +**用于追踪 Workflow 和 Chatflow** + +| 工作流 | Weave 追踪 | +| ---------------------------------------- | ---------------------------- | +| workflow_run_id | id | +| user_id | attributes.user_id | +| workflow | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| 模型 token 消耗（LLM 调用） | summary.usage（按模型） | +| metadata | attributes | +| error | exception | +| 会话 ID | thread_id | +| 父 span（如有） | parent_id | + +**工作流追踪信息** + +* workflow_id - 工作流的唯一标识符 +* conversation_id - 对话 ID +* workflow_run_id - 当前运行的 ID +* tenant_id - 租户 ID +* elapsed_time - 当前运行所花费的时间 +* status - 运行状态 +* version - 工作流版本 +* total_tokens - 当前运行中使用的总令牌数 +* file_list - 处理的文件列表 +* triggered_from - 触发当前运行的来源 +* workflow_run_inputs - 当前运行的输入数据 +* workflow_run_outputs - 当前运行的输出数据 +* error - 当前运行期间遇到的错误 +* query - 运行期间使用的查询 +* workflow_app_log_id - Workflow 应用日志 ID +* message_id - 关联的消息 ID +* start_time - 运行的开始时间 +* end_time - 运行的结束时间 +* workflow node executions - 工作流节点执行的信息 +* 元数据 + * workflow_id - 工作流的唯一标识符 + * conversation_id - 对话 ID + * workflow_run_id - 当前运行的 ID + * tenant_id - 租户 ID + * elapsed_time - 当前运行所花费的时间 + * status - 运行状态 + * version - 工作流版本 + * total_tokens - 当前运行中使用的总令牌数 + * file_list - 处理的文件列表 + * triggered_from - 触发当前运行的来源 + +#### **消息追踪信息** + +**用于追踪与 LLM 相关的对话** + +| 聊天 | Weave 追踪 | +| -------------------------------- | ----------------------------- | +| message_id | id | +| end_user_session_id | attributes.end_user_session_id | +| message | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| 模型 token 消耗（LLM 调用） | summary.usage（按模型） | +| metadata | attributes | +| error | exception | +| 会话 ID | thread_id | + +**消息追踪信息** + +* message_id - 消息 ID +* message_data - 消息数据 +* end_user_session_id - 用户会话 ID +* conversation_model - 对话模式 +* message_tokens - 消息中的令牌数 +* answer_tokens - 回答中的令牌数 +* total_tokens - 消息和回答中的总令牌数 +* error - 错误信息 +* inputs - 输入数据 +* outputs - 输出数据 +* file_list - 处理的文件列表 +* start_time - 开始时间 +* end_time - 结束时间 +* conversation_mode - 对话模式 +* 元数据 + * conversation_id - 对话 ID + * ls_provider - 模型供应商 + * ls_model_name - 模型 ID + * status - 消息状态 + * from_end_user_id - 发送用户的 ID + * from_account_id - 发送账户的 ID + * agent_based - 消息是否基于代理 + * workflow_run_id - 工作流运行 ID + * from_source - 消息来源 + +#### **审核追踪信息** + +**用于追踪对话审核** + +| 审核 | Weave 追踪 | +| ------------- | ---------------------- | +| user_id | attributes.user_id | +| "moderation" | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| action, flagged | output | +| metadata | attributes | +| message_id | parent_id | + +**审核追踪信息** + +* message_id - 消息 ID +* user_id: 用户 ID +* workflow_app_log_id - Workflow 应用日志 ID +* inputs - 审核输入数据 +* message_data - 消息数据 +* flagged - 内容是否被标记为需要注意 +* action - 采取的特定操作 +* preset_response - 预设响应 +* start_time - 审核开始时间 +* end_time - 审核结束时间 +* 元数据 + * message_id - 消息 ID + * action - 采取的特定操作 + * preset_response - 预设响应 + +#### **建议问题追踪信息** + +**用于追踪建议的问题** + +| 建议问题 | Weave 追踪 | +| ---------------------- | ---------------------- | +| user_id | attributes.user_id | +| suggested_question | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| suggested_question | output | +| metadata | attributes | +| message_id | parent_id | + +**消息追踪信息** + +* message_id - 消息 ID +* message_data - 消息数据 +* inputs - 输入内容 +* outputs - 输出内容 +* start_time - 开始时间 +* end_time - 结束时间 +* total_tokens - 令牌数 +* status - 消息状态 +* error - 错误信息 +* from_account_id - 发送账户的 ID +* agent_based - 消息是否基于代理 +* from_source - 消息来源 +* model_provider - 模型供应商 +* model_id - 模型 ID +* suggested_question - 建议的问题 +* level - 状态级别 +* status_message - 状态消息 +* 元数据 + * message_id - 消息 ID + * ls_provider - 模型供应商 + * ls_model_name - 模型 ID + * status - 消息状态 + * from_end_user_id - 发送用户的 ID + * from_account_id - 发送账户的 ID + * workflow_run_id - 工作流运行 ID + * from_source - 消息来源 + +#### **数据集检索追踪信息** + +**用于追踪知识库检索** + +| 数据集检索 | Weave 追踪 | +| --------------------- | --------------------- | +| user_id | attributes.user_id | +| dataset_retrieval | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| documents | output | +| metadata | attributes | +| message_id | parent_id | + +**数据集检索追踪信息** + +* message_id - 消息 ID +* inputs - 输入内容 +* documents - 文档数据 +* start_time - 开始时间 +* end_time - 结束时间 +* message_data - 消息数据 +* 元数据 + * message_id - 消息 ID + * ls_provider - 模型供应商 + * ls_model_name - 模型 ID + * status - 消息状态 + * from_end_user_id - 发送用户的 ID + * from_account_id - 发送账户的 ID + * agent_based - 消息是否基于代理 + * workflow_run_id - 工作流运行 ID + * from_source - 消息来源 + +#### **工具追踪信息** + +**用于追踪工具调用** + +| 工具 | Weave 追踪 | +| --------------------- | ----------------------- | +| user_id | attributes.user_id | +| tool_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| tool_inputs | inputs | +| tool_outputs | output | +| metadata | attributes | +| message_id | parent_id | -## 验证新的追踪记录 +#### **工具追踪信息** -1. 在 Dify 应用中发起一次新请求，等待运行完成。 -2. 在 **追踪应用性能** 中，点击 **Weave** 的 **查看**，打开配置的项目。 -3. 按运行时间找到新的调用记录，打开后查看其中的子调用。 +* message_id - 消息 ID +* tool_name - 工具名称 +* start_time - 开始时间 +* end_time - 结束时间 +* tool_inputs - 工具输入 +* tool_outputs - 工具输出 +* message_data - 消息数据 +* error - 错误信息（如果有） +* inputs - 消息的输入 +* outputs - 消息的输出 +* tool_config - 工具配置 +* time_cost - 时间成本 +* tool_parameters - 工具参数 +* file_url - 关联文件的 URL +* 元数据 + * message_id - 消息 ID + * tool_name - 工具名称 + * tool_inputs - 工具输入 + * tool_outputs - 工具输出 + * tool_config - 工具配置 + * time_cost - 时间成本 + * error - 错误信息（如果有） + * tool_parameters - 工具参数 + * message_file_id - 消息文件 ID + * created_by_role - 创建者的角色 + * created_user_id - 创建者的用户 ID -运行结束后，追踪记录可能需要一段时间才会显示。 +**生成名称追踪信息** -## 故障排查 +**用于追踪对话标题生成** - - - 保存配置时会检查项目是否存在、是否有写入权限，以及追踪服务器是否可访问。确认已选择 Weave 并启用追踪。在 Weave 中打开配置的 entity 和项目，然后重新运行应用。 +| 生成名称 | Weave 追踪 | +| ----------------- | ---------------------- | +| user_id | attributes.user_id | +| generate_name | op_name / display_name | +| start_time | started_at | +| end_time | ended_at | +| inputs | inputs | +| outputs | output | +| metadata | attributes | - 如果仍找不到新运行的追踪记录，让管理员检查 worker 日志和 [追踪数据投递队列](/zh/self-host/deploy/configuration/environments#llmops-追踪投递)。 - - - Dify 的 API 和 worker 必须能访问该地址。容器中的 `localhost` 指向容器自身，因此应填写 Dify 可访问的监控服务器主机名。 +**生成名称追踪信息** - 使用内网 HTTP 端点时，让管理员检查 [SSRF 代理允许列表](/zh/self-host/deploy/configuration/environments#ssrf-代理)，仅放行所需的目标地址。 - - +* conversation_id - 对话 ID +* inputs - 输入数据 +* outputs - 生成的对话名称 +* start_time - 开始时间 +* end_time - 结束时间 +* tenant_id - 租户 ID +* 元数据 + * conversation_id - 对话 ID + * tenant_id - 租户 ID