Ops Trace Data Models#

Overview#

Dify's ops trace system converts runtime events (messages, workflow runs) into structured trace objects for downstream observability providers. The pipeline is:

App invocation
    → TraceTask (queued via TraceQueueManager)
    → TraceTask.execute() → message_trace() / workflow_trace()
    → MessageTraceInfo / WorkflowTraceInfo (Pydantic models)
    → TaskData (serialized to storage)
    → process_trace_tasks Celery task → tracing provider

Entity Definitions#

BaseTraceInfo — shared base#

Defined in api/core/ops/entities/trace_entity.py. All trace info models inherit from this Pydantic BaseModel. Key fields:

app_id is not a top-level model field on either trace class — it lives inside metadata.

MessageTraceInfo#

Defined at lines 109–120. Adds LLM-specific fields: conversation_model, message_tokens, answer_tokens, total_tokens, error, file_list, message_file_data, conversation_mode, and streaming metrics.

WorkflowTraceInfo#

Defined at lines 87–106. Adds workflow-specific fields: workflow_id, tenant_id (top-level, required), workflow_run_id, workflow_run_elapsed_time, workflow_run_status, workflow_run_inputs/outputs/version, total_tokens, and optional conversation_id.

How app_id Flows Into Trace Metadata#

For MessageTraceInfo#

Constructed in message_trace():

1. The Message ORM row is fetched via get_message_data(message_id).
2. message_data.app_id (a non-nullable StringUUID column on Message) is read directly 1.
3. tenant_id is resolved by querying App.tenant_id where App.id == message_data.app_id 2.
4. Both are placed into the metadata dict at construction time 3: metadata["app_id"] = message_data.app_id.

For WorkflowTraceInfo#

Constructed in workflow_trace():

1. The WorkflowRun row is fetched by workflow_run_id.
2. workflow_run.app_id is read directly (the field is required on WorkflowRun).
3. Placed into metadata["app_id"] at construction 4.

TraceTask / TraceQueueManager#

TraceTask is initialized with self.app_id = None 5. When enqueued via TraceQueueManager.add_trace_task(), the manager's own self.app_id (set at construction from the call site) is assigned to trace_task.app_id. This app_id is then used as the storage key when serializing the TaskData to a file for Celery 6.

DB Entity Relationships#

The three source entities each carry app_id as a direct, non-nullable column:

Message carries a direct app_id column (not derived from Conversation), making trace construction efficient — no join is needed to resolve the app. The Message → Conversation link exists for conversation-mode lookups (e.g., fetching conversation_mode during message_trace()), not for app_id resolution 7.

Key Source Files#