💡 深入理解：为什么所有 Metrics 钩子都注册在 After 阶段？

这是一个精心的设计选择，而非偶然。AddAfterInitialize、AddAfterCallTool 等后置钩子确保只有成功处理的请求才被计数，避免了"请求还没处理完就计数"导致的指标失真。唯一的例外是 AddOnError——它注册在全局错误钩子上，专门兜底捕获所有阶段的异常。

另一个值得注意的细节：GetOrCreateCounter 的"动态创建"能力是关键——它允许在运行时根据实际的 client_name、tool_name 动态生成指标，无需预定义所有标签组合。这对 MCP Server 这种工具名、客户端名不可预知的场景至关重要。如果用 Prometheus 官方库，你需要提前 Register 所有可能的指标——在动态场景下几乎不可能。

func New(ms *metrics.Set) *server.Hooks {
	hooks := &server.Hooks{}

	// ① 客户端初始化指标
	hooks.AddAfterInitialize(func(_ context.Context, _ any, message *mcp.InitializeRequest, _ *mcp.InitializeResult) {
		ms.GetOrCreateCounter(fmt.Sprintf(
			`mcp_victoriametrics_initialize_total{client_name="%s",client_version="%s"}`,
			message.Params.ClientInfo.Name,
			message.Params.ClientInfo.Version,
		)).Inc()
	})

	// ② 列表操作指标（工具/资源/提示词）
	hooks.AddAfterListTools(func(_ context.Context, _ any, _ *mcp.ListToolsRequest, _ *mcp.ListToolsResult) {
		ms.GetOrCreateCounter(`mcp_victoriametrics_list_tools_total`).Inc()
	})
	hooks.AddAfterListResources(func(_ context.Context, _ any, _ *mcp.ListResourcesRequest, _ *mcp.ListResourcesResult) {
		ms.GetOrCreateCounter(`mcp_victoriametrics_list_resources_total`).Inc()
	})
	hooks.AddAfterListPrompts(func(_ context.Context, _ any, _ *mcp.ListPromptsRequest, _ *mcp.ListPromptsResult) {
		ms.GetOrCreateCounter(`mcp_victoriametrics_list_prompts_total`).Inc()
	})

	// ③ 工具调用指标（核心业务监控）
	hooks.AddAfterCallTool(func(_ context.Context, _ any, message *mcp.CallToolRequest, result any) {
		isError := false
		if r, ok := result.(*mcp.CallToolResult); ok {
			isError = r.IsError
		}
		ms.GetOrCreateCounter(fmt.Sprintf(
			`mcp_victoriametrics_call_tool_total{name="%s",is_error="%t"}`,
			message.Params.Name,
			isError,
		)).Inc()
	})

	// ④ 提示词获取指标
	hooks.AddAfterGetPrompt(func(_ context.Context, _ any, message *mcp.GetPromptRequest, _ *mcp.GetPromptResult) {
		ms.GetOrCreateCounter(fmt.Sprintf(
			`mcp_victoriametrics_get_prompt_total{name="%s"}`,
			message.Params.Name,
		)).Inc()
	})

	// ⑤ 资源读取指标
	hooks.AddAfterReadResource(func(_ context.Context, _ any, message *mcp.ReadResourceRequest, _ *mcp.ReadResourceResult) {
		ms.GetOrCreateCounter(fmt.Sprintf(
			`mcp_victoriametrics_read_resource_total{uri="%s"}`,
			message.Params.URI,
		)).Inc()
	})

	// ⑥ 全局错误指标
	hooks.AddOnError(func(_ context.Context, _ any, method mcp.MCPMethod, _ any, err error) {
		ms.GetOrCreateCounter(fmt.Sprintf(
			`mcp_victoriametrics_error_total{method="%s",error="%s"}`,
			method,
			err,
		)).Inc()
	})

	return hooks
}

hooks.AddAfterInitialize(func(_ context.Context, _ any, message *mcp.InitializeRequest, _ *mcp.InitializeResult) {
    ms.GetOrCreateCounter(fmt.Sprintf(
        `mcp_victoriametrics_initialize_total{client_name="%s",client_version="%s"}`,
        message.Params.ClientInfo.Name,
        message.Params.ClientInfo.Version,
    )).Inc()
})

• • • • 核心问题：“哪些 AI 客户端（Claude/Cursor/ 自定义 Agent）在使用 MCP Server？各版本占比多少？”
      • 故障排查：若某版本客户端调用异常，可快速定位版本范围
      • 容量规划：根据客户端数量增长趋势，提前扩容 MCP Server
      • 源码细节：注意这里使用的是 AddAfterInitialize（后置钩子），而非 AddBeforeInitialize，确保只有初始化成功的客户端才被计数

hooks.AddAfterListTools(func(_ context.Context, _ any, _ *mcp.ListToolsRequest, _ *mcp.ListToolsResult) {
    ms.GetOrCreateCounter(`mcp_victoriametrics_list_tools_total`).Inc()
})
hooks.AddAfterListResources(func(_ context.Context, _ any, _ *mcp.ListResourcesRequest, _ *mcp.ListResourcesResult) {
    ms.GetOrCreateCounter(`mcp_victoriametrics_list_resources_total`).Inc()
})
hooks.AddAfterListPrompts(func(_ context.Context, _ any, _ *mcp.ListPromptsRequest, _ *mcp.ListPromptsResult) {
    ms.GetOrCreateCounter(`mcp_victoriametrics_list_prompts_total`).Inc()
})

• • • • 基础监控：这三类操作是 MCP Server 的基础心跳，若调用量骤降，可能是客户端连接异常
      • 无标签设计：列表操作无业务区分维度，冗余标签会增加 Prometheus 存储压力（SRE 需关注指标基数）
      • 源码细节：注意回调函数的四个参数全部使用 _ 忽略（context、id、request、result），因为列表操作只需计数，不需要提取任何业务信息

3.2.3、工具调用指标：核心业务监控

hooks.AddAfterCallTool(func(_ context.Context, _ any, message *mcp.CallToolRequest, result any) {
    isError := false
    if r, ok := result.(*mcp.CallToolResult); ok {
        isError = r.IsError
    }
    ms.GetOrCreateCounter(fmt.Sprintf(
        `mcp_victoriametrics_call_tool_total{name="%s",is_error="%t"}`,
        message.Params.Name,
        isError,
    )).Inc()
})

SRE 运维价值（核心）：

func Merge(hooksList ...*server.Hooks) *server.Hooks {
    combined := &server.Hooks{}
    for _, h := range hooksList {
        if h == nil {
            continue
        }
        combined.OnRegisterSession = append(combined.OnRegisterSession, h.OnRegisterSession...)
        combined.OnUnregisterSession = append(combined.OnUnregisterSession, h.OnUnregisterSession...)
        combined.OnBeforeAny = append(combined.OnBeforeAny, h.OnBeforeAny...)
        combined.OnSuccess = append(combined.OnSuccess, h.OnSuccess...)
        combined.OnError = append(combined.OnError, h.OnError...)
        combined.OnRequestInitialization = append(combined.OnRequestInitialization, h.OnRequestInitialization...)
        combined.OnBeforeInitialize = append(combined.OnBeforeInitialize, h.OnBeforeInitialize...)
        combined.OnAfterInitialize = append(combined.OnAfterInitialize, h.OnAfterInitialize...)
        combined.OnBeforePing = append(combined.OnBeforePing, h.OnBeforePing...)
        combined.OnAfterPing = append(combined.OnAfterPing, h.OnAfterPing...)
        combined.OnBeforeSetLevel = append(combined.OnBeforeSetLevel, h.OnBeforeSetLevel...)
        combined.OnAfterSetLevel = append(combined.OnAfterSetLevel, h.OnAfterSetLevel...)
        combined.OnBeforeListResources = append(combined.OnBeforeListResources, h.OnBeforeListResources...)
        combined.OnAfterListResources = append(combined.OnAfterListResources, h.OnAfterListResources...)
        combined.OnBeforeListResourceTemplates = append(combined.OnBeforeListResourceTemplates, h.OnBeforeListResourceTemplates...)
        combined.OnAfterListResourceTemplates = append(combined.OnAfterListResourceTemplates, h.OnAfterListResourceTemplates...)
        combined.OnBeforeReadResource = append(combined.OnBeforeReadResource, h.OnBeforeReadResource...)
        combined.OnAfterReadResource = append(combined.OnAfterReadResource, h.OnAfterReadResource...)
        combined.OnBeforeListPrompts = append(combined.OnBeforeListPrompts, h.OnBeforeListPrompts...)
        combined.OnAfterListPrompts = append(combined.OnAfterListPrompts, h.OnAfterListPrompts...)
        combined.OnBeforeGetPrompt = append(combined.OnBeforeGetPrompt, h.OnBeforeGetPrompt...)
        combined.OnAfterGetPrompt = append(combined.OnAfterGetPrompt, h.OnAfterGetPrompt...)
        combined.OnBeforeListTools = append(combined.OnBeforeListTools, h.OnBeforeListTools...)
        combined.OnAfterListTools = append(combined.OnAfterListTools, h.OnAfterListTools...)
        combined.OnBeforeCallTool = append(combined.OnBeforeCallTool, h.OnBeforeCallTool...)
        combined.OnAfterCallTool = append(combined.OnAfterCallTool, h.OnAfterCallTool...)
    }
    return combined
}

// main.go 关键代码
ms := metrics.NewSet()

// 分别创建 Metrics Hooks 和 Logger Hooks
metricsHooks := hooks.New(ms)
loggingHooks := hooks.NewLoggerHooks()

// 合并为一个 Hooks 实例
combinedHooks := hooks.Merge(metricsHooks, loggingHooks)

// 传入 MCP Server
s := server.NewMCPServer(
    "VictoriaMetrics",
    fmt.Sprintf("v%s (date: %s)", version, date),
    server.WithRecovery(),
    server.WithLogging(),
    server.WithToolCapabilities(false),
    server.WithResourceCapabilities(false, false),
    server.WithPromptCapabilities(false),
    server.WithHooks(combinedHooks),  // 注入合并后的 Hooks
    server.WithInstructions(`...`),
)

💡 深入理解：Merge 为什么是"粘合剂"而非"继承链"？

传统 OOP 思维可能会用继承来扩展 Hooks（如 MetricsHooks extends BaseHooks），但 Go 没有继承，Merge 用的是组合（Composition）思想——每个 Hooks 实例是独立的功能单元，Merge 只是把它们的回调切片拼接在一起。这意味着你可以像搭积木一样自由组合：Merge(metrics, logging) 用于生产环境，Merge(logging) 用于调试环境，Merge(metrics, logging, tracing) 用于全链路观测。

需要警惕的是 Merge 的顺序敏感性：append 保证先传入的 Hooks 先执行。在 Merge(metricsHooks, loggingHooks) 中，Metrics 钩子先于 Logging 钩子执行——如果 Metrics 钩子 panic（虽然不应该），后续的 Logging 钩子就不会执行。这也是为什么 server.WithRecovery() 在 main.go 中被启用的原因之一。

// 1. 实现Tracing Hooks
func NewTracingHooks(tracer *otel.Tracer) *server.Hooks {
    hooks := &server.Hooks{}
    hooks.AddBeforeAny(func(ctx context.Context, id any, method mcp.MCPMethod, message any) {
        // 启动span
        ctx, span := tracer.Start(ctx, string(method))
        span.SetAttribute("request_id", fmt.Sprintf("%v", id))
        span.SetAttribute("session_id", extractSessionID(ctx))
    })
    hooks.AddOnSuccess(func(ctx context.Context, id any, method mcp.MCPMethod, message any, result any) {
        // 结束span（成功）
        span := trace.SpanFromContext(ctx)
        span.End()
    })
    hooks.AddOnError(func(ctx context.Context, id any, method mcp.MCPMethod, message any, err error) {
        // 结束span（失败）
        span := trace.SpanFromContext(ctx)
        span.RecordError(err)
        span.End()
    })
    return hooks
}

// 2. 合并到现有Hooks（在 main.go 中）
metricsHooks := hooks.New(ms)
loggingHooks := hooks.NewLoggerHooks()
tracingHooks := NewTracingHooks(tracer)
combinedHooks := hooks.Merge(metricsHooks, loggingHooks, tracingHooks)

// 3. 传入MCP Server
s := server.NewMCPServer(
    "VictoriaMetrics",
    version,
    server.WithHooks(combinedHooks),
)

SRE 价值：新增链路追踪完全不影响现有监控 / 日志逻辑，符合 开闭原则，降低变更风险。

⚠️ 注意：上述 Tracing 示例中 AddBeforeAny 钩子修改了 ctx（ctx, span := tracer.Start(ctx, ...)），但当前 mcp-go 框架的 BeforeAnyHookFunc 签名不返回 ctx，因此修改后的 ctx 不会传递到后续钩子和业务逻辑中。实际生产中需要通过其他方式（如 context.WithValue 在请求入口注入 span）来实现完整的链路追踪。

六、SRE 生产环境落地最佳实践

6.1、指标优化

6.2、日志优化

• • • 日志采样：高并发场景下，对普通 Info 日志做 1:10 采样，保留 Error 日志全量，降低存储成本。
    • 敏感信息过滤：若message中包含敏感数据（如 API 密钥），在toJSON函数中过滤。
    • 日志分级：将AfterCallTool的错误日志升级为 Error 级别，便于告警。

6.3、性能优化

• • • 监控失效演练：模拟metrics.Set初始化失败，验证业务流程是否不受影响。
    • 日志序列化失败演练：传入无法序列化的message，验证toJSON是否返回空字符串且业务正常。
    • Hooks 合并失败演练：传入 nil Hooks，验证Merge函数是否能正常处理。

🎯 全文核心洞察：三个函数撑起整个可观测性体系

回顾整个 hooks.go，核心代码量不到 200 行，却只用了三个函数就构建了完整的可观测性体系：New(ms) 负责指标采集（7 个 Counter 覆盖全业务），NewLoggerHooks() 负责结构化日志（三层漏斗覆盖全生命周期），Merge() 负责组合扩展（积木式拼装任意观测能力）。

这种设计的精髓在于"约束即自由"——mcp-go 框架通过 server.Hooks 结构体约束了所有可能的挂载点，而 VictoriaMetrics 团队在这些约束内，用最少的代码实现了最大的运维价值。对 SRE 来说，这不仅是一个可以直接复用的可观测性方案，更是一种值得借鉴的架构思维：把横切关注点从业务代码中彻底剥离，让监控成为架构的一部分，而非事后的补丁。