feat: trace

astrbot/builtin_stars/astrbot/process_llm_request.py

@@ -38,7 +38,12 @@ class ProcessLLMRequest:
         req.func_tool.add_tool(LOCAL_PYTHON_TOOL)
 
     async def _ensure_persona(
-        self, req: ProviderRequest, cfg: dict, umo: str, platform_type: str
+        self,
+        req: ProviderRequest,
+        cfg: dict,
+        umo: str,
+        platform_type: str,
+        event: AstrMessageEvent,
     ):
         """确保用户人格已加载"""
         if not req.conversation:
@@ -121,6 +126,9 @@ class ProcessLLMRequest:
             req.func_tool = toolset
         else:
             req.func_tool.merge(toolset)
+        event.trace.record(
+            "sel_persona", persona_id=persona_id, persona_toolset=toolset.names()
+        )
         logger.debug(f"Tool set for persona {persona_id}: {toolset.names()}")
 
     async def _ensure_img_caption(
@@ -225,7 +233,7 @@ class ProcessLLMRequest:
             # inject persona for this request
             platform_type = event.get_platform_name()
             await self._ensure_persona(
-                req, cfg, event.unified_msg_origin, platform_type
+                req, cfg, event.unified_msg_origin, platform_type, event
             )
 
             # image caption

astrbot/core/event_bus.py

@@ -54,6 +54,7 @@ class EventBus:
             event (AstrMessageEvent): 事件对象
 
         """
+        event.trace.record("event_dispatch", config_name=conf_name)
         # 如果有发送者名称: [平台名] 发送者名称/发送者ID: 消息概要
         if event.get_sender_name():
             logger.info(

astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py

@@ -691,6 +691,17 @@ class InternalAgentSubStage(Stage):
                 if action_type == "live":
                     req.system_prompt += f"\n{LIVE_MODE_SYSTEM_PROMPT}\n"
 
+                event.trace.record(
+                    "astr_agent_prepare",
+                    system_prompt=req.system_prompt,
+                    tools=req.func_tool.names() if req.func_tool else [],
+                    stream=streaming_response,
+                    chat_provider={
+                        "id": provider.provider_config.get("id", ""),
+                        "model": provider.get_model(),
+                    },
+                )
+
                 await agent_runner.reset(
                     provider=provider,
                     request=req,
@@ -795,12 +806,20 @@ class InternalAgentSubStage(Stage):
                     ):
                         yield
 
+                final_resp = agent_runner.get_final_llm_resp()
+
+                event.trace.record(
+                    "astr_agent_complete",
+                    stats=agent_runner.stats.to_dict(),
+                    resp=final_resp.completion_text if final_resp else None,
+                )
+
                 # 检查事件是否被停止，如果被停止则不保存历史记录
                 if not event.is_stopped():
                     await self._save_to_history(
                         event,
                         req,
-                        agent_runner.get_final_llm_resp(),
+                        final_resp,
                         agent_runner.run_context.messages,
                         agent_runner.stats,
                     )

astrbot/core/pipeline/scheduler.py

@@ -85,4 +85,6 @@ class PipelineScheduler:
         if isinstance(event, WebChatMessageEvent | WecomAIBotMessageEvent):
             await event.send(None)
 
+        event.trace.record("event_end")
+
         logger.debug("pipeline 执行完毕。")

astrbot/core/platform/astr_message_event.py

@@ -4,6 +4,7 @@ import hashlib
 import re
 import uuid
 from collections.abc import AsyncGenerator
+from time import time
 from typing import Any
 
 from astrbot import logger
@@ -22,6 +23,7 @@ from astrbot.core.message.message_event_result import MessageChain, MessageEvent
 from astrbot.core.platform.message_type import MessageType
 from astrbot.core.provider.entities import ProviderRequest
 from astrbot.core.utils.metrics import Metric
+from astrbot.core.utils.trace import TraceSpan
 
 from .astrbot_message import AstrBotMessage, Group
 from .message_session import MessageSesion, MessageSession  # noqa
@@ -59,6 +61,21 @@ class AstrMessageEvent(abc.ABC):
         self._result: MessageEventResult | None = None
         """消息事件的结果"""
 
+        self.created_at = time()
+        """事件创建时间(Unix timestamp)"""
+        self.trace = TraceSpan(
+            name="AstrMessageEvent",
+            umo=self.unified_msg_origin,
+            sender_name=self.get_sender_name(),
+            message_outline=self.get_message_outline(),
+        )
+        """用于记录事件处理的 TraceSpan 对象"""
+        self.span = self.trace
+        """事件级 TraceSpan(别名: span)"""
+
+        self.trace.record("umo", umo=self.unified_msg_origin)
+        self.trace.record("event_created", created_at=self.created_at)
+
         self._has_send_oper = False
         """在此次事件中是否有过至少一次发送消息的操作"""
         self.call_llm = False

astrbot/core/utils/trace.py

@@ -0,0 +1,54 @@
+import time
+import uuid
+from typing import Any
+
+from astrbot import logger
+from astrbot.core.log import LogQueueHandler
+
+_cached_log_broker = None
+
+
+def _get_log_broker():
+    global _cached_log_broker
+    if _cached_log_broker is not None:
+        return _cached_log_broker
+    for handler in logger.handlers:
+        if isinstance(handler, LogQueueHandler):
+            _cached_log_broker = handler.log_broker
+            return _cached_log_broker
+    return None
+
+
+class TraceSpan:
+    def __init__(
+        self,
+        name: str,
+        umo: str | None = None,
+        sender_name: str | None = None,
+        message_outline: str | None = None,
+    ) -> None:
+        self.span_id = str(uuid.uuid4())
+        self.name = name
+        self.umo = umo
+        self.sender_name = sender_name
+        self.message_outline = message_outline
+        self.started_at = time.time()
+
+    def record(self, action: str, **fields: Any) -> None:
+        payload = {
+            "type": "trace",
+            "level": "TRACE",
+            "time": time.time(),
+            "span_id": self.span_id,
+            "name": self.name,
+            "umo": self.umo,
+            "sender_name": self.sender_name,
+            "message_outline": self.message_outline,
+            "action": action,
+            "fields": fields,
+        }
+        log_broker = _get_log_broker()
+        if log_broker:
+            log_broker.publish(payload)
+            return
+        logger.info(f"[trace] {payload}")

dashboard/src/components/shared/TraceDisplayer.vue

@@ -0,0 +1,458 @@
+<script setup>
+import axios from 'axios';
+import { EventSourcePolyfill } from 'event-source-polyfill';
+</script>
+
+<template>
+  <div class="trace-wrapper">
+    <div class="trace-table" ref="scrollEl">
+      <div class="trace-row trace-header">
+        <div class="trace-cell time">Time</div>
+        <div class="trace-cell span">Event ID</div>
+        <div class="trace-cell umo">UMO</div>
+        <!-- <div class="trace-cell count">Records</div> -->
+        <!-- <div class="trace-cell last">Last</div> -->
+        <div class="trace-cell sender">Sender</div>
+        <div class="trace-cell outline">Outline</div>
+        <div class="trace-cell fields"></div>
+      </div>
+      <div class="trace-group" :class="{ highlight: highlightMap[event.span_id] }" v-for="event in events"
+        :key="event.span_id">
+        <div class="trace-row trace-event">
+          <div class="trace-cell time">{{ formatTime(event.first_time) }}</div>
+          <div class="trace-cell span" :title="event.span_id">
+            <div class="event-title">
+              {{ shortSpan(event.span_id) }}
+            </div>
+          </div>
+          <div class="trace-cell umo">{{ event.umo }}</div>
+          <!-- <div class="trace-cell count">
+            <div class="event-meta">{{ event.records.length }}</div>
+          </div> -->
+          <!-- <div class="trace-cell last">
+            <div class="event-meta">{{ formatTime(event.last_time) }}</div>
+          </div> -->
+          <div class="trace-cell sender">
+            <div class="event-sub" style="white-space: nowrap; overflow: hidden; text-overflow: ellipsis;">{{
+              event.sender_name || '-' }}</div>
+          </div>
+          <div class="trace-cell outline">
+            <div class="event-sub outline">{{ event.message_outline || '-' }}</div>
+          </div>
+          <div class="trace-cell fields event-controls">
+            <v-btn size="x-small" variant="text" color="primary" @click="toggleEvent(event.span_id)">
+              {{ event.collapsed ? 'Expand' : 'Collapse' }}
+            </v-btn>
+          </div>
+        </div>
+        <div class="trace-records" v-if="!event.collapsed">
+          <div class="trace-record" v-for="record in getVisibleRecords(event)" :key="record.key">
+            <div class="trace-record-time">{{ record.timeLabel }}</div>
+            <div class="trace-record-action">{{ record.action }}</div>
+            <pre class="trace-record-fields">{{ record.fieldsText }}</pre>
+          </div>
+          <div class="event-more" v-if="event.visibleCount < event.records.length">
+            <v-btn size="x-small" variant="tonal" color="primary" @click="showMore(event.span_id)">
+              Show more
+            </v-btn>
+          </div>
+        </div>
+      </div>
+      <div v-if="events.length === 0" class="trace-empty">No trace data yet.</div>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'TraceDisplayer',
+  props: {
+    autoScroll: {
+      type: Boolean,
+      default: true
+    },
+    maxItems: {
+      type: Number,
+      default: 300
+    }
+  },
+  data() {
+    return {
+      events: [],
+      eventIndex: {},
+      highlightMap: {},
+      highlightTimers: {},
+      eventSource: null,
+      retryTimer: null,
+      retryAttempts: 0,
+      maxRetryAttempts: 10,
+      baseRetryDelay: 1000,
+      lastEventId: null
+    };
+  },
+  async mounted() {
+    await this.fetchTraceHistory();
+    this.connectSSE();
+  },
+  beforeUnmount() {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    this.retryAttempts = 0;
+  },
+  methods: {
+    async fetchTraceHistory() {
+      try {
+        const res = await axios.get('/api/log-history');
+        const logs = res.data?.data?.logs || [];
+        const traces = logs.filter((item) => item.type === 'trace');
+        this.processNewTraces(traces);
+      } catch (err) {
+        console.error('Failed to fetch trace history:', err);
+      }
+    },
+    connectSSE() {
+      if (this.eventSource) {
+        this.eventSource.close();
+        this.eventSource = null;
+      }
+
+      const token = localStorage.getItem('token');
+
+      this.eventSource = new EventSourcePolyfill('/api/live-log', {
+        headers: {
+          Authorization: token ? `Bearer ${token}` : ''
+        },
+        heartbeatTimeout: 300000,
+        withCredentials: true
+      });
+
+      this.eventSource.onopen = () => {
+        this.retryAttempts = 0;
+        if (!this.lastEventId) {
+          this.fetchTraceHistory();
+        }
+      };
+
+      this.eventSource.onmessage = (event) => {
+        try {
+          if (event.lastEventId) {
+            this.lastEventId = event.lastEventId;
+          }
+
+          const payload = JSON.parse(event.data);
+          if (payload?.type !== 'trace') {
+            return;
+          }
+          this.processNewTraces([payload]);
+        } catch (e) {
+          console.error('Failed to parse trace payload:', e);
+        }
+      };
+
+      this.eventSource.onerror = (err) => {
+        if (this.eventSource) {
+          this.eventSource.close();
+          this.eventSource = null;
+        }
+
+        if (this.retryAttempts >= this.maxRetryAttempts) {
+          console.error('Trace stream reached max retry attempts.');
+          return;
+        }
+
+        const delay = Math.min(
+          this.baseRetryDelay * Math.pow(2, this.retryAttempts),
+          30000
+        );
+
+        if (this.retryTimer) {
+          clearTimeout(this.retryTimer);
+          this.retryTimer = null;
+        }
+
+        this.retryTimer = setTimeout(async () => {
+          this.retryAttempts++;
+          if (!this.lastEventId) {
+            await this.fetchTraceHistory();
+          }
+          this.connectSSE();
+        }, delay);
+      };
+    },
+    processNewTraces(newTraces) {
+      if (!newTraces || newTraces.length === 0) return;
+
+      let hasUpdate = false;
+      const touched = new Set();
+      newTraces.forEach((trace) => {
+        if (!trace.span_id) return;
+        const recordKey = `${trace.time}-${trace.span_id}-${trace.action}`;
+        let event = this.eventIndex[trace.span_id];
+        if (!event) {
+          event = {
+            span_id: trace.span_id,
+            name: trace.name,
+            umo: trace.umo,
+            sender_name: trace.sender_name,
+            message_outline: trace.message_outline,
+            first_time: trace.time,
+            last_time: trace.time,
+            collapsed: true,
+            visibleCount: 20,
+            records: []
+          };
+          this.eventIndex[trace.span_id] = event;
+          this.events.push(event);
+          hasUpdate = true;
+        }
+
+        const exists = event.records.some((item) => item.key === recordKey);
+        if (exists) return;
+
+        event.records.push({
+          time: trace.time,
+          action: trace.action,
+          fieldsText: this.formatFields(trace.fields),
+          timeLabel: this.formatTime(trace.time),
+          key: recordKey
+        });
+        if (!event.first_time || trace.time < event.first_time) {
+          event.first_time = trace.time;
+        }
+        if (!event.last_time || trace.time > event.last_time) {
+          event.last_time = trace.time;
+        }
+        if (!event.sender_name && trace.sender_name) {
+          event.sender_name = trace.sender_name;
+        }
+        if (!event.message_outline && trace.message_outline) {
+          event.message_outline = trace.message_outline;
+        }
+        touched.add(trace.span_id);
+        hasUpdate = true;
+      });
+
+      if (hasUpdate) {
+        this.events.forEach((event) => {
+          event.records.sort((a, b) => b.time - a.time);
+        });
+        this.events.sort((a, b) => b.first_time - a.first_time);
+        if (this.events.length > this.maxItems) {
+          const overflow = this.events.length - this.maxItems;
+          const removed = this.events.splice(this.maxItems, overflow);
+          removed.forEach((event) => {
+            delete this.eventIndex[event.span_id];
+          });
+        }
+        touched.forEach((spanId) => {
+          this.pulseEvent(spanId);
+        });
+      }
+    },
+    scrollToBottom() {
+      const el = this.$refs.scrollEl;
+      if (!el) return;
+      el.scrollTop = el.scrollHeight;
+    },
+    toggleEvent(spanId) {
+      const event = this.eventIndex[spanId];
+      if (!event) return;
+      event.collapsed = !event.collapsed;
+    },
+    showMore(spanId) {
+      const event = this.eventIndex[spanId];
+      if (!event) return;
+      event.visibleCount = Math.min(event.records.length, event.visibleCount + 20);
+    },
+    pulseEvent(spanId) {
+      if (!spanId) return;
+      if (this.highlightTimers[spanId]) {
+        clearTimeout(this.highlightTimers[spanId]);
+      }
+      this.highlightMap = { ...this.highlightMap, [spanId]: true };
+      const remove = setTimeout(() => {
+        const next = { ...this.highlightMap };
+        delete next[spanId];
+        this.highlightMap = next;
+        const timers = { ...this.highlightTimers };
+        delete timers[spanId];
+        this.highlightTimers = timers;
+      }, 1200);
+      this.highlightTimers = { ...this.highlightTimers, [spanId]: remove };
+    },
+    getVisibleRecords(event) {
+      if (!event.records.length) return [];
+      return event.records.slice(0, event.visibleCount);
+    },
+    formatTime(ts) {
+      if (!ts) return '';
+      const date = new Date(ts * 1000);
+      const base = date.toLocaleString();
+      const ms = String(date.getMilliseconds()).padStart(3, '0');
+      return `${base}.${ms}`;
+    },
+    shortSpan(spanId) {
+      if (!spanId) return '';
+      return spanId.slice(0, 8);
+    },
+    formatFields(fields) {
+      if (!fields) return '';
+      try {
+        const text = JSON.stringify(fields, null, 2);
+        if (text.length > 2000) {
+          return `${text}`;
+        }
+        return text;
+      } catch (e) {
+        return String(fields);
+      }
+    }
+  }
+};
+</script>
+
+<style scoped>
+.trace-wrapper {
+  height: 100%;
+}
+
+.trace-table {
+  background: transparent;
+  border-radius: 0;
+  padding: 0;
+  height: calc(100vh - 240px);
+  overflow-y: auto;
+  color: #2b3340;
+  font-family: 'Fira Code', monospace;
+}
+
+.trace-row {
+  display: grid;
+  grid-template-columns: 200px 100px 300px 90px 180px 140px 200px 1fr;
+  gap: 12px;
+}
+
+.trace-group {
+  border-bottom: 1px solid rgba(15, 23, 42, 0.08);
+  background: transparent;
+  padding: 8px 0;
+}
+
+.trace-group.highlight {
+  background: rgba(59, 130, 246, 0.08);
+  transition: background 0.6s ease;
+}
+
+.trace-event {
+  align-items: start;
+}
+
+.trace-header {
+  font-weight: 600;
+  color: #6b7280;
+  border-bottom: 1px solid rgba(15, 23, 42, 0.12);
+  padding-bottom: 10px;
+}
+
+.trace-cell {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 12px;
+}
+
+.event-title {
+  font-weight: 600;
+  color: #1f2937;
+}
+
+.event-meta {
+  font-size: 12px;
+  color: #6b7280;
+  margin-top: 4px;
+}
+
+.event-sub {
+  font-size: 12px;
+  color: #4b5563;
+  margin-top: 2px;
+  word-break: break-word;
+}
+
+.event-sub.outline {
+  color: #6b7280;
+}
+
+.event-controls {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.trace-cell.fields pre {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: #4b5563;
+}
+
+.trace-empty {
+  padding: 24px;
+  text-align: center;
+  color: #6b7280;
+}
+
+@media (max-width: 1200px) {
+  .trace-row {
+    grid-template-columns: 140px 160px 300px 70px 140px 180px 1fr;
+  }
+
+  .trace-cell.fields {
+    grid-column: 1 / -1;
+  }
+}
+
+.trace-record {
+  display: grid;
+  grid-template-columns: 200px 120px 1fr;
+  gap: 8px;
+  padding: 2px 0;
+}
+
+.trace-record:last-child {
+  border-bottom: none;
+}
+
+.trace-record-time {
+  color: #6b7280;
+  font-size: 11px;
+}
+
+.trace-record-action {
+  color: #1f2937;
+  font-weight: 600;
+  font-size: 11px;
+}
+
+.trace-record-fields {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: #4b5563;
+  font-size: 10px;
+}
+
+.event-more {
+  display: flex;
+  justify-content: center;
+  padding: 6px 0 2px;
+}
+
+.trace-records {
+  padding: 4px 0 2px 0;
+}
+</style>

dashboard/src/i18n/loader.ts

@@ -46,6 +46,7 @@ export class I18nLoader {
       { name: 'features/config', path: 'features/config.json' },
       { name: 'features/config-metadata', path: 'features/config-metadata.json' },
       { name: 'features/console', path: 'features/console.json' },
+      { name: 'features/trace', path: 'features/trace.json' },
       { name: 'features/about', path: 'features/about.json' },
       { name: 'features/settings', path: 'features/settings.json' },
       { name: 'features/auth', path: 'features/auth.json' },
@@ -295,4 +296,4 @@ export class I18nLoader {
   }
 
 
-} 
+} 

dashboard/src/i18n/locales/en-US/core/navigation.json

@@ -11,6 +11,7 @@
   "conversation": "Conversations",
   "sessionManagement": "Custom Rules",
   "console": "Console",
+  "trace": "Trace",
   "alkaid": "Alkaid Lab",
   "knowledgeBase": "Knowledge Base",
   "about": "About",

dashboard/src/i18n/locales/en-US/features/trace.json

@@ -0,0 +1,7 @@
+{
+  "title": "Trace",
+  "autoScroll": {
+    "enabled": "Auto-scroll: On",
+    "disabled": "Auto-scroll: Off"
+  }
+}

dashboard/src/i18n/locales/zh-CN/core/navigation.json

@@ -11,6 +11,7 @@
   "conversation": "对话数据",
   "sessionManagement": "自定义规则",
   "console": "平台日志",
+  "trace": "追踪",
   "alkaid": "Alkaid",
   "knowledgeBase": "知识库",
   "about": "关于",
@@ -30,4 +31,4 @@
     "selectVersion": "选择版本",
     "current": "当前"
   }
-}
+}

dashboard/src/i18n/locales/zh-CN/features/trace.json

@@ -0,0 +1,7 @@
+{
+  "title": "追踪",
+  "autoScroll": {
+    "enabled": "自动滚动：开",
+    "disabled": "自动滚动：关"
+  }
+}

dashboard/src/i18n/translations.ts

@@ -19,6 +19,7 @@ import zhCNPlatform from './locales/zh-CN/features/platform.json';
 import zhCNConfig from './locales/zh-CN/features/config.json';
 import zhCNConfigMetadata from './locales/zh-CN/features/config-metadata.json';
 import zhCNConsole from './locales/zh-CN/features/console.json';
+import zhCNTrace from './locales/zh-CN/features/trace.json';
 import zhCNAbout from './locales/zh-CN/features/about.json';
 import zhCNSettings from './locales/zh-CN/features/settings.json';
 import zhCNAuth from './locales/zh-CN/features/auth.json';
@@ -56,6 +57,7 @@ import enUSPlatform from './locales/en-US/features/platform.json';
 import enUSConfig from './locales/en-US/features/config.json';
 import enUSConfigMetadata from './locales/en-US/features/config-metadata.json';
 import enUSConsole from './locales/en-US/features/console.json';
+import enUSTrace from './locales/en-US/features/trace.json';
 import enUSAbout from './locales/en-US/features/about.json';
 import enUSSettings from './locales/en-US/features/settings.json';
 import enUSAuth from './locales/en-US/features/auth.json';
@@ -97,6 +99,7 @@ export const translations = {
       config: zhCNConfig,
       'config-metadata': zhCNConfigMetadata,
       console: zhCNConsole,
+      trace: zhCNTrace,
       about: zhCNAbout,
       settings: zhCNSettings,
       auth: zhCNAuth,
@@ -142,6 +145,7 @@ export const translations = {
       config: enUSConfig,
       'config-metadata': enUSConfigMetadata,
       console: enUSConsole,
+      trace: enUSTrace,
       about: enUSAbout,
       settings: enUSSettings,
       auth: enUSAuth,
@@ -169,4 +173,4 @@ export const translations = {
   }
 };
 
-export type TranslationData = typeof translations; 
+export type TranslationData = typeof translations; 

dashboard/src/layouts/full/vertical-sidebar/sidebarItem.ts

@@ -72,6 +72,11 @@ const sidebarItem: menu[] = [
         icon: 'mdi-console',
         to: '/console'
       },
+      {
+        title: 'core.navigation.trace',
+        icon: 'mdi-timeline-text-outline',
+        to: '/trace'
+      },
     ]
   }
   // {

dashboard/src/router/MainRoutes.ts

@@ -61,6 +61,11 @@ const MainRoutes = {
       path: '/console',
       component: () => import('@/views/ConsolePage.vue')
     },
+    {
+      name: 'Trace',
+      path: '/trace',
+      component: () => import('@/views/TracePage.vue')
+    },
     {
       name: 'NativeKnowledgeBase',
       path: '/knowledge-base',

dashboard/src/views/TracePage.vue

@@ -0,0 +1,25 @@
+<script setup>
+import TraceDisplayer from '@/components/shared/TraceDisplayer.vue';
+import { useModuleI18n } from '@/i18n/composables';
+
+const { tm } = useModuleI18n('features/trace');
+</script>
+
+<template>
+  <div style="height: 100%;">
+    <div
+      style="background-color: var(--v-theme-surface); padding: 8px 16px; border-radius: 8px; margin-bottom: 16px; display: flex; flex-direction: row; align-items: center; justify-content: space-between;">
+      <h4>{{ tm('title') }}</h4>
+    </div>
+    <TraceDisplayer />
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'TracePage',
+  components: {
+    TraceDisplayer
+  }
+};
+</script>