1. 项目概述从可观测性痛点出发为什么我们需要SigNoz在云原生和微服务架构成为主流的今天一个应用可能由数十甚至上百个服务组成它们分布在不同的容器、节点甚至云区域中。当用户反馈“页面加载慢”或“功能报错”时传统的监控方式——比如盯着服务器CPU/内存图表——常常让我们陷入困境。问题到底出在哪里是某个数据库查询变慢了还是下游的API服务响应超时是网络延迟还是代码逻辑有缺陷这种“盲人摸象”的体验相信很多运维和开发同学都深有感触。可观测性Observability就是为了解决这个问题而生的理念。它不再局限于传统的指标监控而是强调通过系统外部输出的数据主要是日志、指标、链路追踪这三大支柱去理解系统内部的实际状态。你可以把它想象成给复杂的分布式系统装上了一套“X光CT心电图”的综合诊断系统。而SigNoz正是这样一款开源、一体化的可观测性平台它旨在将指标Metrics、链路追踪Traces和日志Logs统一在一个界面中让你能像福尔摩斯一样顺着线索快速定位问题根源。我最初接触SigNoz是因为团队在使用传统的ELKElasticsearch, Logstash, Kibana堆栈和PrometheusGrafana组合时遇到了数据孤岛和关联分析困难的问题。查日志要切到Kibana看指标要打开Grafana分析调用链又得用Jaeger几个工具之间数据不通切换成本高排查效率低下。SigNoz提出的“All-in-One”解决方案直接击中了这个痛点。它使用OpenTelemetry作为数据采集的标准后端用ClickHouse存储所有可观测性数据前端提供了统一的分析和可视化界面。简单说它想成为可观测性领域的“瑞士军刀”。2. 核心架构与设计哲学拆解SigNoz的“一体化”实现SigNoz的设计目标很明确降低可观测性的使用门槛和运维成本同时提供强大的关联分析能力。要理解它为什么能实现这一点我们需要深入其核心架构。2.1 数据采集层拥抱OpenTelemetry标准SigNoz本身不生产数据它是数据的搬运工和加工者。在数据采集上它坚定地拥抱了CNCF的OpenTelemetryOTel项目。这是一个关键的战略选择。OTel旨在为遥测数据链路、指标、日志提供一套统一的标准API、SDK和收集器解决以往各家探针Agent互不兼容的乱象。对于应用开发者而言这意味着你只需要集成OTel的SDK通过配置就能将数据发送到SigNoz而无需绑定任何特定厂商。SigNoz推荐使用OpenTelemetry Collector作为数据收集的代理。Collector可以以边车模式部署接收来自应用SDK的数据进行过滤、加工、批处理然后统一发送到SigNoz的后端。这种架构的好处是解耦了应用与后端存储Collector可以承担数据缓冲、重试、格式转换等脏活累活提升了整个数据管道的可靠性。注意虽然SigNoz主推OTel但它也兼容其他协议。例如它的存储引擎ClickHouse可以直接接收Prometheus格式的指标这意味着你现有的Prometheus生态可以逐步迁移降低了 adoption 门槛。2.2 存储与查询引擎ClickHouse的强大支撑可观测性数据是典型的时间序列数据并且数据量巨大尤其是链路追踪数据一次用户请求可能产生数十条Span。传统的时序数据库或搜索引擎在面对高基数和复杂查询时往往力不从心。SigNoz选择了ClickHouse作为其核心存储引擎这是一个非常明智且高性能的选择。ClickHouse是一个列式数据库特别擅长高速分析查询。对于可观测性场景它的优势非常明显高吞吐写入能够轻松应对海量Span和指标数据的实时写入。快速聚合查询计算P99延迟、错误率等聚合指标的速度极快。高基数支持能够高效处理链路追踪中常见的、带有大量标签如用户ID、订单号的数据查询。SigNoz的后端服务用Go编写主要负责接收来自Collector的数据并将其写入ClickHouse。同时它也提供了一系列查询API供前端界面调用。这种将存储与计算分离的架构使得系统可以独立地扩展存储层或查询层。2.3 前端与用户体验以问题排查为中心的设计SigNoz的UI是其一大亮点。它没有简单地堆砌图表而是围绕“问题排查”的工作流进行设计。首页通常是一个仪表盘展示全局的关键指标如请求速率、错误率、P99延迟等。当发现异常比如错误率飙升你可以直接点击图表钻取。最强大的功能在于Trace Explorer和Logs Explorer的深度关联。在Trace Explorer中你可以看到所有分布式链路并可以通过服务名、操作名、状态码、甚至自定义标签进行筛选。点击一条慢链路界面会清晰地展示出整个调用链的火焰图直观地告诉你时间都花在哪一步。更关键的是你可以在同一个视图下直接查看这条链路在任意节点产生的日志以及该服务当时的关键指标如CPU、内存。这种“指标-链路-日志”的无缝跳转将原本需要在三个工具间进行的操作浓缩在几次点击之内极大提升了排查效率。3. 从零开始部署与配置SigNoz理论讲得再多不如亲手搭一个。SigNoz提供了多种部署方式这里我们以最常用的Docker Compose方式在本地或测试环境进行部署为例这也是官方推荐给新手的入门方式。3.1 环境准备与前置条件首先确保你的机器满足以下条件操作系统Linux (Ubuntu/CentOS等) 或 macOS。Windows用户建议使用WSL2。Docker版本20.10及以上。Docker Compose版本v2及以上。硬件资源建议至少4核CPU8GB内存50GB磁盘空间。ClickHouse对内存和I/O比较敏感资源越多性能越好。网络需要能访问Docker Hub等镜像仓库。检查Docker和Docker Compose是否安装docker --version docker-compose --version3.2 使用Docker Compose一键部署这是最快捷的方式。从SigNoz的GitHub仓库拉取部署文件。git clone -b main https://github.com/SigNoz/signoz.git cd signoz/deploy/docker/clickhouse-setup这个目录下的docker-compose.yaml文件定义了所有服务前端、后端、ClickHouse、Zookeeper为ClickHouse提供协调服务等。启动所有服务docker-compose up -d-d参数表示在后台运行。首次运行会从Docker Hub拉取所有镜像可能需要几分钟时间取决于你的网速。启动完成后你可以通过以下命令检查服务状态docker-compose ps你应该看到所有服务frontend, query-service, alertmanager, clickhouse等的状态都是“Up”。3.3 初始访问与配置服务启动后在浏览器中访问http://localhost:3301。你会看到SigNoz的初始化界面。创建管理员账户输入你的姓名、邮箱和密码完成首次注册。这个账户拥有最高权限。第一步配置登录后系统会引导你进行初始配置比如设置组织名称。数据发送配置这是最关键的一步。SigNoz会提供一个清晰的指引页面告诉你如何配置OpenTelemetry Collector将数据发送到本地的SigNoz后端通常是http://your-signoz-host:4317或http://your-signoz-host:4318分别对应gRPC和HTTP协议。实操心得在本地测试时我推荐使用localhost或宿主机的IP。如果在云服务器上部署记得在安全组或防火墙中开放前端端口默认3301和OTLP接收端口4317, 4318。生产环境务必使用HTTPS并配置身份认证。3.4 接入第一个应用以Python Flask为例平台搭好了现在让我们接入一个简单的Python Flask应用产生一些可观测性数据。安装OpenTelemetry依赖pip install opentelemetry-distro opentelemetry-exporter-otlp pip install flask opentelemetry-bootstrap -a install创建一个简单的Flask应用app.pyfrom flask import Flask import time import random app Flask(__name__) app.route(/) def hello(): # 模拟一些处理时间 time.sleep(random.uniform(0.01, 0.1)) return Hello, Observability! app.route(/api/slow) def slow_api(): # 模拟一个慢接口 time.sleep(random.uniform(0.5, 2.0)) return This was a slow response. app.route(/api/error) def error_api(): # 模拟一个会随机出错的接口 if random.random() 0.7: raise Exception(Random error occurred!) return Everything is OK. if __name__ __main__: app.run(host0.0.0.0, port5000)通过环境变量配置并启动应用 我们需要告诉OTel SDK将数据发送到哪里以及采集哪些信息。export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4318 # SigNoz OTLP HTTP接收端点 export OTEL_SERVICE_NAMEpython-flask-demo export OTEL_RESOURCE_ATTRIBUTESdeployment.environmenttesting opentelemetry-instrument flask run --host0.0.0.0 --port5000opentelemetry-instrument命令会自动为Flask应用注入追踪、指标和日志的采集能力。生成流量并查看数据 使用curl或浏览器多次访问http://localhost:5000/、/api/slow和/api/error。for i in {1..50}; do curl http://localhost:5000/; done for i in {1..10}; do curl http://localhost:5000/api/slow; done for i in {1..10}; do curl http://localhost:5000/api/error; done等待一两分钟然后刷新SigNoz的仪表盘localhost:3301。你应该能在“服务”列表中看到python-flask-demo点击进入可以查看请求速率、延迟分布和错误率。切换到“Traces”标签页可以看到详细的调用链路。4. 核心功能深度使用与问题排查成功接入数据后我们来深入探索SigNoz的核心功能并分享一些实际使用中会遇到的问题和技巧。4.1 服务地图与依赖分析在SigNoz的“服务”页面有一个非常直观的“服务地图”视图。它会自动根据链路追踪数据绘制出服务之间的调用关系图。节点大小可能代表请求量边颜色可能代表错误率或延迟。这个功能对于理解微服务架构的拓扑结构、发现不合理的依赖或瓶颈服务至关重要。使用技巧在新服务上线或架构变更后定期查看服务地图可以快速发现意料之外的调用关系或循环依赖。4.2 链路追踪的深度钻取与对比分析Trace Explorer是排查复杂问题的利器。除了基本的过滤你还可以按异常筛选直接过滤出所有状态为“Error”的链路集中火力分析失败原因。按耗时筛选找出最慢的1%的请求例如延迟大于1秒的分析其共性。对比分析选择两条相似的链路一条成功、一条失败一条快、一条慢SigNoz可以并排展示它们的火焰图帮助你快速定位差异点。差异可能体现在某个下游服务的调用耗时、返回结果大小甚至是传递的标签属性上。踩坑记录初期我们发现很多链路缺少关键的业务标签如user_id,order_id导致无法将系统问题与具体的业务场景关联。解决办法是在代码中通过OTel API手动添加这些属性。例如在Python中tracer.set_attribute(“user.id”, user_id)。给Span打上丰富的、有业务意义的标签是发挥可观测性威力的关键一步。4.3 日志与链路的无缝关联这是SigNoz相较于传统分离式工具的最大优势之一。在链路详情页面你可以直接看到一个“Logs”标签页。点击它SigNoz会自动将当前链路Trace ID作为过滤条件查询出在这条请求生命周期内产生的所有相关日志。实现原理这要求你的应用日志必须包含Trace ID。opentelemetry-instrument会自动为Python的logging库注入处理器将Trace ID和Span ID添加到每一条日志记录中。对于其他语言也需要类似配置确保日志上下文包含trace_id和span_id字段。常见问题为什么我的日志没有关联上检查日志格式确认日志输出中是否包含了trace_id和span_id。通常它们会以JSON字段或特定格式的字符串出现。检查日志采集器配置如果你使用Fluentd、Logstash或Vector等工具采集日志需要确保它们将日志原样或解析后包含这些字段发送到SigNoz。SigNoz的日志接收器期望一个特定的JSON格式。检查字段映射在SigNoz的日志查询界面检查是否正确地识别了trace_id字段。有时字段名可能不匹配需要在查询时手动指定。4.4 告警配置与管理监控的最终目的是为了及时发现问题。SigNoz内置了告警功能基于Prometheus的Alertmanager。你可以在UI上配置告警规则。典型告警场景配置高错误率在过去5分钟内某个服务的HTTP错误码5xx比率超过1%。高延迟在过去5分钟内某个接口的P99延迟超过预设阈值如500ms。服务下线某个服务的实例心跳丢失超过1分钟。配置告警时需要定义规则名称清晰描述告警内容。PromQL表达式用于计算告警条件。例如sum(rate(signoz_calls_total{service_name”my-service”, status_code”STATUS_CODE_ERROR”}[5m])) / sum(rate(signoz_calls_total{service_name”my-service”}[5m])) 0.01持续时间条件持续多久才触发告警避免毛刺。告警级别Critical, Error, Warning等。通知渠道需要配置Alertmanager的接收器以支持发送邮件、Slack、Webhook等。注意事项告警配置的黄金法则是“少而精”。避免告警疲劳只对真正影响业务和用户体验的指标设置告警。同时确保告警信息包含足够的上文比如服务名、实例IP、当前值、阈值和相关的仪表盘链接方便接收人快速定位。5. 生产环境部署考量与性能调优将SigNoz用于生产环境需要考虑更多关于高可用、可扩展性和数据保留的策略。5.1 高可用与集群化部署单机Docker Compose部署只适用于测试。生产环境需要集群化部署以保障可用性。ClickHouse集群生产数据必须存储在ClickHouse集群中。SigNoz官方提供了基于ClickHouse Keeper替代ZooKeeper的集群配置示例。你需要部署多个ClickHouse节点并配置分片和副本。查询服务与前端SigNoz的query-service和frontend是无状态服务可以通过Kubernetes Deployment或简单的负载均衡器后面部署多个副本来实现水平扩展和高可用。OpenTelemetry Collector建议以DaemonSet方式部署在Kubernetes每个节点上或以Sidecar方式部署确保应用数据能就近发送避免单点故障。5.2 数据保留与存储成本优化可观测性数据量巨大全量永久存储成本极高。必须制定数据保留策略。分层存储ClickHouse支持TTL生存时间。可以为不同精度的数据设置不同的TTL。例如原始链路数据保留7天用于详细问题排查。按小时/天聚合的指标数据保留30天用于趋势分析。超低频的聚合数据如日级别报表保留1年。采样策略对于超高流量的服务全量采集所有链路可能不经济。可以在OpenTelemetry Collector层配置采样策略。例如对健康、低延迟的请求进行低概率采样如1%而对错误或高延迟的请求进行全量采样。这能大幅降低存储和计算开销同时不丢失关键问题信息。日志级别控制避免在代码中全量打印DEBUG或INFO日志。使用动态日志级别调整在正常情况下只记录WARN和ERROR在排查问题时再临时调低级别。5.3 性能监控与调优SigNoz本身也是一个需要被监控的系统。监控SigNoz自身利用SigNoz监控SigNoz。为SigNoz的各个组件query-service, clickhouse等也配置OTel instrumentation将其指标和日志纳入同一个平台管理。这能帮你发现SigNoz自身的瓶颈比如查询慢、内存不足等。ClickHouse调优这是性能关键。关注ClickHouse的查询日志、慢查询、内存使用和磁盘I/O。根据数据特点调整MergeTree表引擎的索引粒度、分区键和主键。定期执行OPTIMIZE TABLE来合并数据部分提升查询性能。查询优化在SigNoz面板中构建复杂查询或大盘时注意查询的时间范围和数据粒度。避免在UI上直接查询长达30天的原始链路数据这可能导致浏览器或查询服务超时。尽量使用预聚合的指标或缩小查询范围。6. 与其他工具的对比与生态集成选择工具时了解其在生态中的位置很重要。SigNoz vs. 传统组合 (Prometheus Grafana Loki Tempo/Jaeger)优势开箱即用的统一体验数据关联性强学习曲线相对平缓避免了维护多个独立系统的复杂性。劣势相比高度成熟的Prometheus生态其告警规则库、仪表盘社区、 exporter 丰富度仍有差距。Grafana的图表定制能力和插件生态目前更强大。SigNoz vs. 商业可观测性平台 (Datadog, New Relic, Dynatrace)优势完全开源自主可控无供应商锁定成本极低主要是基础设施成本。数据隐私有保障。劣势需要自行运维和调优企业级功能如高级机器学习异常检测、深度代码级诊断可能缺失或不如商业产品成熟。生态集成建议与现有Prometheus集成你可以让SigNoz和Prometheus并存。使用SigNoz作为链路和日志的核心同时让Prometheus继续采集基础设施和中间件指标并通过Remote Write将指标数据也写入ClickHouse最终在SigNoz UI上统一查看。这是一种平滑的迁移路径。与CI/CD流水线集成在部署新版本后可以自动查询SigNoz的API对比部署前后关键服务的错误率和延迟变化实现基于可观测性的自动化发布验证。