nightingale Documentation

Nightingale is to monitoring and alerting what Grafana is to visualization.

13,208 stars Go Go 1 file · ~5,647 tokens #alerting#ccf#metrics#monitoring#nightingale#observability#open-falcon#time-series
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy nightingale on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name nightingale -p 17000:17000 --restart always ccfos/nightingale:latest

File: README.md

English | 中文

🎯 What is Nightingale

Nightingale is an open-source monitoring project that focuses on alerting. Similar to Grafana, Nightingale also connects with various existing data sources. However, while Grafana emphasizes visualization, Nightingale places greater emphasis on the alerting engine, as well as the processing and distribution of alarms.

💡 Nightingale now speaks MCP out of the box: the server itself exposes a built-in MCP endpoint at /mcp, so AI assistants can manage alerting and explore observability data in natural language with no extra process to deploy. See MCP Server below.

The Nightingale project was initially developed and open-sourced by DiDi.inc. On May 11, 2022, it was donated to the Open Source Development Committee of the China Computer Federation (CCF ODTC).

💡 How Nightingale Works

Many users have already collected metrics and log data. In this case, you can connect your storage repositories (such as VictoriaMetrics, ElasticSearch, etc.) as data sources in Nightingale. This allows you to configure alerting rules and notification rules within Nightingale, enabling the generation and distribution of alarms.

Nightingale itself does not provide monitoring data collection capabilities. We recommend using Categraf as the collector, which integrates seamlessly with Nightingale.

Categraf can collect monitoring data from operating systems, network devices, various middleware, and databases. It pushes this data to Nightingale via the Prometheus Remote Write protocol. Nightingale then stores the monitoring data in a time-series database (such as Prometheus, VictoriaMetrics, etc.) and provides alerting and visualization capabilities.

For certain edge data centers with poor network connectivity to the central Nightingale server, we offer a distributed deployment mode for the alerting engine. In this mode, even if the network is disconnected, the alerting functionality remains unaffected.

In the above diagram, Data Center A has a good network with the central data center, so it uses the Nightingale process in the central data center as the alerting engine. Data Center B has a poor network with the central data center, so it deploys n9e-edge as the alerting engine to handle alerting for its own data sources.

🤖 MCP Server

Nightingale has a built-in MCP Server: the n9e process itself serves the Model Context Protocol at /mcp over the Streamable HTTP transport. Any MCP client — Claude Code / Claude Desktop, Cursor, ChatGPT connectors, or your own agent — can query and manage Nightingale in natural language, with no extra process to deploy.

Connecting a client

The endpoint is http(s)://<nightingale>:17000/mcp — a root path, not under /api/n9e. Authenticate with a personal access token (create one in the web UI under Profile → Token Management) sent in the X-User-Token header:

json
{
  "mcpServers": {
    "nightingale": {
      "type": "http",
      "url": "http://127.0.0.1:17000/mcp",
      "headers": { "X-User-Token": "<your-token>" }
    }
  }
}

Every tool call is dispatched onto Nightingale's own HTTP API inside the process, carrying your token, so RBAC and business-group permissions apply exactly as they do for that user in the UI — a client can never reach anything its token's owner cannot.

Tools

74 fine-grained tools (42 read, 32 write) across 13 toolsets: alerts, targets, datasource, mutes, busi_groups, notify_rules, alert_subscribes, event_pipelines, users, metrics, logs, dashboards, roles.

The endpoint is read-only by default — the write tools (create / update / delete) are an explicit config opt-in.

Configuration

Everything below is optional; /mcp is enabled out of the box (etc/config.toml):

toml
[HTTP.A2A]
# DisableMCP = true                        # turn off /mcp (Disable = true turns off /a2a as well)
# MCPToolsets = ["alerts", "dashboards"]   # restrict the exposed toolsets; empty = all of them
# MCPEnableWriteTools = true               # also register the write tools; read-only by default

/mcp reuses [HTTP.TokenAuth] for authentication, so keep that enabled.

OAuth 2.1 instead of a token

/mcp also accepts OAuth access tokens via Authorization: Bearer, in two flavors:

  • Nightingale acts as the authorization server itself, with RFC 7591 dynamic client registration and PKCE, so hosted clients such as Claude or ChatGPT can connect with zero pre-registration — see doc/api/mcp-oauth-as.md.
  • Nightingale acts as a resource server for your existing enterprise IdP (Keycloak, Entra ID, Okta, Auth0), mapping each token to its local user so permissions and audit stay per-person — see doc/api/a2a-oauth-rs.md.

Alongside MCP, the same process exposes an A2A endpoint at /a2a that wraps Nightingale's built-in AI assistant for agent-to-agent integration (doc/api/a2a.md). If you would rather run MCP as a separate process against a remote Nightingale, the standalone n9e-mcp-server provides the same tools.

🔕 Alert Noise Reduction, Escalation, and Collaboration

Nightingale focuses on being an alerting engine, responsible for generating alarms and flexibly distributing them based on rules. It supports 20 built-in notification medias (such as phone calls, SMS, email, DingTalk, Slack, etc.).

If you have more advanced requirements, such as:

  • Want to consolidate events from multiple monitoring systems into one platform for unified noise reduction, response handling, and data analysis.
  • Want to support personnel scheduling, practice on-call culture, and support alert escalation (to avoid missing alerts) and collaborative handling.

Then Nightingale is not suitable. It is recommended that you choose on-call products such as PagerDuty and FlashDuty. These products are simple and easy to use.

🗨️ Communication Channels

🔑 Key Features

  • Nightingale supports alerting rules, mute rules, subscription rules, and notification rules. It natively supports 20 types of notification media and allows customization of message templates.

  • It supports event pipelines for Pipeline processing of alarms, facilitating automated integration with in-house systems. For example, it can append metadata to alarms or perform relabeling on events.

  • It introduces the concept of business groups and a permission system to manage various rules in a categorized manner.

  • Many databases and middleware come with built-in alert rules that can be directly imported and used. It also supports direct import of Prometheus alerting rules.

  • It supports alerting self-healing, which automatically triggers a script to execute predefined logic after an alarm is generated—such as cleaning up disk space or capturing the current system state.

  • Nightingale archives historical alarms and supports multi-dimensional query and statistics.

  • It supports flexible aggregation grouping, allowing a clear view of the distribution of alarms across the company.

  • Nightingale has built-in metric descriptions, dashboards, and alerting rules for common operating systems, middleware, and databases, which are contributed by the community with varying quality.

  • It directly receives data via multiple protocols such as Remote Write, OpenTSDB, Datadog, and Falcon, integrates with various Agents.

  • It supports data sources like Prometheus, ElasticSearch, Loki, ClickHouse, MySQL, Postgres, allowing alerting based on data from these sources.

  • Nightingale can be easily embedded into internal enterprise systems (e.g. Grafana, CMDB), and even supports configuring menu visibility for these embedded systems.

  • Nightingale supports dashboard functionality, including common chart types, and comes with pre-built dashboards. The image above is a screenshot of one of these dashboards.

  • If you are already accustomed to Grafana, it is recommended to continue using Grafana for visualization, as Grafana has deeper expertise in this area.

  • For machine-related monitoring data collected by Categraf, it is advisable to use Nightingale's built-in dashboards for viewing. This is because Categraf's metric naming follows Telegraf's convention, which differs from that of Node Exporter.

  • Due to Nightingale's concept of business groups (where machines can belong to different groups), there may be scenarios where you only want to view machines within the current business group on the dashboard. Thus, Nightingale's dashboards can be linked with business groups for interactive filtering.

🌟 Stargazers over time

🔥 Users

🤝 Community Co-Building

  • ❇️ Please read the Nightingale Open Source Project and Community Governance Draft. We sincerely welcome every user, developer, company, and organization to use Nightingale, actively report bugs, submit feature requests, share best practices, and help build a professional and active open-source community.
  • ❤️ Nightingale Contributors

📜 License

File: cli/upgrade/readme.md

v5 升级 v6 手册

  1. 操作之前，记得备注下数据库！

  2. 需要先将你正在使用的夜莺数据源表结构更新到和 v5.15.0 一致，release 页面有每个版本表结构的更新说明，可以根据你正在使用的版本，按照说明，逐个执行的更新表结构的语句

  3. 解压 n9e 安装包，导入 upgrade.sql 到 n9e_v5 数据库

text
mysql -h 127.0.0.1 -u root -p1234 < cli/upgrade/upgrade.sql
  1. 执行 n9e-cli 完成数据库表结构升级, webapi.conf 为 v5 版本 n9e-webapi 正在使用的配置文件
text
./n9e-cli --upgrade --config webapi.conf
  1. 修改 n9e 配置文件中的数据库为 n9e_v5，启动 n9e 进程
text
nohup ./n9e &> n9e.log &
  1. n9e 监听的端口为 17000，需要将之前的 web 端口和数据上报的端口，都调整为 17000

File: doc/active-contributors.md

Active Contributors

File: doc/committers.md

Committers

File: doc/community-governance.md

夜莺监控是一款开源云原生监控系统，由滴滴设计开发，2020 年 3 月份开源之后，凭借其优秀的产品设计、灵活性架构和明确清晰的定位，夜莺监控快速发展为国内最活跃的企业级云原生监控方案。截止当前，在 Github 上已经迭代发布了 70 多个版本，获得了 5K 多个 Star，80 多位代码贡献者。快速的迭代，也让夜莺监控的用户群越来越大，涉及各行各业。

更进一步，夜莺监控于 2022 年 5 月 11 日，正式捐赠予中国计算机学会开源发展委员会 CCF ODC，为 CCF ODC 成立后接受捐赠的第一个开源项目。

开源项目要更有生命力，离不开开放的治理架构和源源不断的开发者共同参与。夜莺监控项目加入 CCF 开源大家庭后，能在计算机学会的支持和带动下，进一步结合云原生、可观测、国产化等多个技术发展的需求，建立开放、中立的开源治理架构，打造更专业、有活力的开发者社区。

今天，我们郑重发布夜莺监控开源社区治理架构，并公示相关的任命和社区荣誉，期待开源的道路上，一起同行。

夜莺监控开源社区架构

User|用户

欢迎任何个人、公司以及组织，使用夜莺监控，并积极的反馈 bug、提交功能需求、以及相互帮助，我们推荐使用 Github Issue 来跟踪 bug 和管理需求。

社区用户，可以通过在 Who is Using Nightingale 登记您的使用情况，并分享您使用夜莺监控的经验，将会自动进入 END USERS 文件列表，并获得社区的 VIP Support。

Contributor|贡献者

欢迎每一位用户，包括但不限于以下方式参与到夜莺开源社区并做出贡献：

  1. 在 Github Issue 中积极参与讨论，参与社区活动；
  2. 提交代码补丁；
  3. 翻译、修订、补充和完善文档；
  4. 分享夜莺监控的使用经验，积极布道；
  5. 提交建议 / 批评；

年度累计向 CCFOS/NIGHTINGALE 提交 5 个PR（被合并），或者因为其他贡献被项目管委会一致认可，将会自动进入到 ACTIVE CONTRIBUTORS 列表，并获得夜莺开源社区颁发的证书，享有夜莺开源社区一定的权益和福利。

所有向 CCFOS/NIGHTINGALE 提交过PR（被合并），或者做出过重要贡献的 Contributor，都会被永久记载于 CONTRIBUTORS 列表。

Committer|提交者

Committer 是指拥有 CCFOS/NIGHTINGALE 代码仓库写操作权限的贡献者。原则上 Committer 能够自主决策某个代码补丁是否可以合入到夜莺代码仓库，但是项目管委会拥有最终的决策权。

Committer 承担以下一个或多个职责：

  • 积极回应 Issues；
  • Review PRs；
  • 参加开发者例行会议，积极讨论项目规划和技术方案；
  • 代表夜莺开源社区出席相关技术会议并做演讲；

Committer 记录并公示于 COMMITTERS 列表，并获得夜莺开源社区颁发的证书，以及享有夜莺开源社区的各种权益和福利。

PMC|项目管委会

PMC（项目管委会）作为一个实体，来管理和领导夜莺项目，为整个项目的发展全权负责。项目管委会相关内容记录并公示于文件PMC.

  • 项目管委会成员(PMC Member)，从 Contributor 或者 Committer 中选举产生，他们拥有 CCFOS/NIGHTINGALE 代码仓库的写操作权限，拥有 Nightingale 社区相关事务的投票权、以及提名 Committer 候选人的权利。
  • 项目管委会主席(PMC Chair)，从项目管委会成员中投票产生。管委会主席是 CCF ODC 和项目管委会之间的沟通桥梁，履行特定的项目管理职责。

Communication|沟通机制

  1. 我们推荐使用邮件列表来反馈建议（待发布）；
  2. 我们推荐使用 Github Issue 跟踪 bug 和管理需求；
  3. 我们推荐使用 Github Milestone 来管理项目进度和规划；
  4. 我们推荐使用腾讯会议来定期召开项目例会（会议 ID 待发布）；

Documentation|文档

  1. 我们推荐使用 Github Pages 来沉淀文档；
  2. 我们推荐使用 Gitlink Wiki 来沉淀 FAQ；

Operation|运营机制

  1. 我们定期组织用户、贡献者、项目管委会成员之间的沟通会议，讨论项目开发的目标、方案、进度，以及讨论相关需求的合理性、优先级等议题；
  2. 我们定期组织 meetup （线上&线下），创造良好的用户交流分享环境，并沉淀相关内容到文档站点；
  3. 我们定期组织夜莺开发者大会，分享 best user story、同步年度开发目标和计划、讨论新技术方向等；

Philosophy|社区指导原则

尊重、认可和记录每一位贡献者的工作。

关于提问的原则

按照尊重、认可、记录每一位贡献者的工作原则，我们提倡高效的提问，这既是对开发者时间的尊重，也是对整个社区的知识沉淀的贡献：

  1. 提问之前请先查阅 FAQ ；
  2. 提问之前请先搜索 Github Issues；
  3. 我们优先推荐通过提交 Github Issue 来提问，如果有问题点击这里 | 有需求建议点击这里；

File: doc/contributors.md

Contributors

File: doc/end-users.md

End Users

File: doc/pmc.md

PMC Chair

PMC Co-Chair

PMC Member

File: doc/README.bak.md

English | 中文

功能和特点

  • 开箱即用
    • 支持 Docker、Helm Chart、云服务等多种部署方式，集数据采集、监控告警、可视化为一体，内置多种监控仪表盘、快捷视图、告警规则模板，导入即可快速使用，大幅降低云原生监控系统的建设成本、学习成本、使用成本；
  • 专业告警
    • 可视化的告警配置和管理，支持丰富的告警规则，提供屏蔽规则、订阅规则的配置能力，支持告警多种送达渠道，支持告警自愈、告警事件管理等；
    • 推荐您使用夜莺的同时，无缝搭配FlashDuty，实现告警聚合收敛、认领、升级、排班、协同，让告警的触达既高效，又确保告警处理不遗漏、做到件件有回响。
  • 云原生
    • 以交钥匙的方式快速构建企业级的云原生监控体系，支持 Categraf、Telegraf、Grafana-agent 等多种采集器，支持 Prometheus、VictoriaMetrics、M3DB、ElasticSearch、Jaeger 等多种数据源，兼容支持导入 Grafana 仪表盘，与云原生生态无缝集成；
  • 高性能 高可用
    • 得益于夜莺的多数据源管理引擎，和夜莺引擎侧优秀的架构设计，借助于高性能时序库，可以满足数亿时间线的采集、存储、告警分析场景，节省大量成本；
    • 夜莺监控组件均可水平扩展，无单点，已在上千家企业部署落地，经受了严苛的生产实践检验。众多互联网头部公司，夜莺集群机器达百台，处理数亿级时间线，重度使用夜莺监控；
  • 灵活扩展 中心化管理
    • 夜莺监控，可部署在 1 核 1G 的云主机，可在上百台机器集群化部署，可运行在 K8s 中；也可将时序库、告警引擎等组件下沉到各机房、各 Region，兼顾边缘部署和中心化统一管理，解决数据割裂，缺乏统一视图的难题；
  • 开放社区
    • 托管于中国计算机学会开源发展委员会，有快猫星云和众多公司的持续投入，和数千名社区用户的积极参与，以及夜莺监控项目清晰明确的定位，都保证了夜莺开源社区健康、长久的发展。活跃、专业的社区用户也在持续迭代和沉淀更多的最佳实践于产品中；

使用场景

  1. 如果您希望在一个平台中，统一管理和查看 Metrics、Logging、Tracing 数据，推荐你使用夜莺：
  2. 如果您在使用 Prometheus 过程中，有以下的一个或者多个需求场景，推荐您无缝升级到夜莺：
    • Prometheus、Alertmanager、Grafana 等多个系统较为割裂，缺乏统一视图，无法开箱即用;
    • 通过修改配置文件来管理 Prometheus、Alertmanager 的方式，学习曲线大，协同有难度;
    • 数据量过大而无法扩展您的 Prometheus 集群；
    • 生产环境运行多套 Prometheus 集群，面临管理和使用成本高的问题；
  3. 如果您在使用 Zabbix，有以下的场景，推荐您升级到夜莺：
    • 监控的数据量太大，希望有更好的扩展解决方案；
    • 学习曲线高，多人多团队模式下，希望有更好的协同使用效率；
    • 微服务和云原生架构下，监控数据的生命周期多变、监控数据维度基数高，Zabbix 数据模型不易适配；
    • 了解更多Zabbix和夜莺监控的对比，推荐您进一步阅读Zabbix 和夜莺监控选型对比
  4. 如果您在使用 Open-Falcon，我们推荐您升级到夜莺：
  5. 我们推荐您使用 Categraf 作为首选的监控数据采集器：
    • Categraf 是夜莺监控的默认采集器，采用开放插件机制和 All-in-one 的设计理念，同时支持 metric、log、trace、event 的采集。Categraf 不仅可以采集 CPU、内存、网络等系统层面的指标，也集成了众多开源组件的采集能力，支持K8s生态。Categraf 内置了对应的仪表盘和告警规则，开箱即用。

文档

English Doc | 中文文档

产品示意图

https://user-images.githubusercontent.com/792850/216888712-2565fcea-9df5-47bd-a49e-d60af9bd76e8.mp4

夜莺架构

夜莺监控可以接收各种采集器上报的监控数据（比如 Categraf、telegraf、grafana-agent、Prometheus），并写入多种流行的时序数据库中（可以支持Prometheus、M3DB、VictoriaMetrics、Thanos、TDEngine等），提供告警规则、屏蔽规则、订阅规则的配置能力，提供监控数据的查看能力，提供告警自愈机制（告警触发之后自动回调某个webhook地址或者执行某个脚本），提供历史告警事件的存储管理、分组查看的能力。

中心汇聚式部署方案

夜莺只有一个模块，就是 n9e，可以部署多个 n9e 实例组成集群，n9e 依赖 2 个存储，数据库、Redis，数据库可以使用 MySQL 或 Postgres，自己按需选用。

n9e 提供的是 HTTP 接口，前面负载均衡可以是 4 层的，也可以是 7 层的。一般就选用 Nginx 就可以了。

n9e 这个模块接收到数据之后，需要转发给后端的时序库，相关配置是：

toml
[Pushgw]
LabelRewrite = true
[[Pushgw.Writers]] 
Url = "http://127.0.0.1:9090/api/v1/write"

注意：虽然数据源可以在页面配置了，但是上报转发链路，还是需要在配置文件指定。

所有机房的 agent（ 比如 Categraf、Telegraf、 Grafana-agent、Datadog-agent ），都直接推数据给 n9e，这个架构最为简单，维护成本最低。当然，前提是要求机房之间网络链路比较好，一般有专线。如果网络链路不好，则要使用下面的部署方式了。

边缘下沉式混杂部署方案

这个图尝试解释 3 种不同的情形，比如 A 机房和中心网络链路很好，Categraf 可以直接汇报数据给中心 n9e 模块，另一个机房网络链路不好，就需要把时序库下沉部署，时序库下沉了，对应的告警引擎和转发网关也都要跟随下沉，这样数据不会跨机房传输，比较稳定。但是心跳还是需要往中心心跳，要不然在对象列表里看不到机器的 CPU、内存使用率。还有的时候，可能是接入的一个已有的 Prometheus，数据采集没有走 Categraf，那此时只需要把 Prometheus 作为数据源接入夜莺即可，可以在夜莺里看图、配告警规则，但是就是在对象列表里看不到，也不能使用告警自愈的功能，问题也不大，核心功能都不受影响。

边缘机房，下沉部署时序库、告警引擎、转发网关的时候，要注意，告警引擎需要依赖数据库，因为要同步告警规则，转发网关也要依赖数据库，因为要注册对象到数据库里去，需要打通相关网络，告警引擎和转发网关都不用Redis，所以无需为 Redis 打通网络。

VictoriaMetrics 集群架构

如果单机版本的时序数据库（比如 Prometheus） 性能有瓶颈或容灾较差，我们推荐使用 VictoriaMetrics，VictoriaMetrics 架构较为简单，性能优异，易于部署和运维，架构图如上。VictoriaMetrics 更详尽的文档，还请参考其官网。

夜莺社区

开源项目要更有生命力，离不开开放的治理架构和源源不断的开发者和用户共同参与，我们致力于建立开放、中立的开源治理架构，吸纳更多来自企业、高校等各方面对云原生监控感兴趣、有热情的开发者，一起打造有活力的夜莺开源社区。关于《夜莺开源项目和社区治理架构（草案）》，请查阅 COMMUNITY GOVERNANCE.

我们欢迎您以各种方式参与到夜莺开源项目和开源社区中来，工作包括不限于：

尊重、认可和记录每一位贡献者的工作是夜莺开源社区的第一指导原则，我们提倡高效的提问，这既是对开发者时间的尊重，也是对整个社区知识沉淀的贡献：

  • 提问之前请先查阅 FAQ
  • 我们使用论坛进行交流，有问题可以到这里搜索、提问

Who is using Nightingale

您可以通过在 Who is Using Nightingale 登记您的使用情况，分享您的使用经验。

Stargazers over time

Contributors

License

Apache License V2.0

加入交流群

File: integrations/ZooKeeper/markdown/README.md

zookeeper

ZooKeeper >=3.6.0 内置 Prometheus 支持，但本目录的 Zookeeper - exporter 仪表盘查询的是 Categraf ZooKeeper input 生成的 zk_* 指标。要直接使用当前模板，应按下文启用 Categraf input。

如果改为抓取 ZooKeeper 原生 Prometheus 端点，需要先确认其指标名是否为 zk_up、zk_znode_count、zk_packets_sent 等；指标名不一致时必须同步修改模板，不能只替换采集端点。

说明

Categraf ZooKeeper input 移植于 dabealu/zookeeper-exporter，通过 ZooKeeper 四字命令获取监控信息。本次使用 ZooKeeper 3.9 和该 input 完成 16/16 查询验证。

需要注意的是，在 zookeeper v3.4.10 以后添加了四字命令白名单，需要在 zookeeper 的配置文件 zoo.cfg 中新增白名单配置:

text
4lw.commands.whitelist=mntr,ruok

生产环境只开放采集所需命令，不要无条件配置为 *。

配置

zookeeper 插件的配置在 conf/input.zookeeper/zookeeper.toml 集群中的多个实例地址请用空格分隔：

toml
[[instances]]
cluster_name = "dev-zk-cluster"
addresses = "127.0.0.1:2181"
timeout = 10
labels = { job = "zookeeper", instance = "zk-01:2181" }

如果要监控多个 zookeeper 集群，就增加 instances 即可：

toml
[[instances]]
cluster_name = "dev-zk-cluster"
addresses = "127.0.0.1:2181"
timeout = 10
labels = { job = "zookeeper-a", instance = "zk-a-01:2181" }

[[instances]]
cluster_name = "test-zk-cluster"
addresses = "127.0.0.1:2181 127.0.0.1:2182 127.0.0.1:2183"
timeout = 10
labels = { job = "zookeeper-b" }

验证：

bash
./categraf --test --inputs zookeeper

至少确认 zk_up、zk_znode_count 和 zk_packets_sent，并保留模板变量使用的 job、instance 标签。

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#alerting Browse alerting catalog → #ccf Browse ccf catalog → #metrics Browse metrics catalog → #monitoring Browse monitoring catalog → #nightingale Browse nightingale catalog → #observability Browse observability catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →