# 铁路可观测性 Railway.com 可观测性综合指南，包括内置指标、可定制仪表板、警报（专业计划）以及与 Grafana/Prometheus/Loki/Tempo 的外部 OTEL 集成。 ## 概述 Railway 提供多层可观测能力： * 内置指标（CPU、内存、磁盘、网络） *带有拖放小部件的可定制仪表板 * 通过电子邮件和 webhook 集成发出警报（专业计划） * 通过 Grafana Alloy 进行外部 OTEL 集成 * 完整的可观测性堆栈部署（Grafana模板） **关键词**：指标、监控、可观察性、仪表板、警报、Grafana、Prometheus、Loki、Tempo、OTEL、Alloy、Railway ## 何时使用此技能 * 设置铁路服务监控 * 创建自定义可观察性仪表板 * 配置资源阈值警报 * 集成外部监控系统 * 部署 Grafana 可观测性堆栈 * 分析服务绩效指标 * 解决资源问题 * 设置分布式跟踪 ## 快速入门 ### 1\.访问内置可观察性仪表板导航到您的铁路项目：铁路仪表板 → 项目 → 服务 → 指标选项卡 **你所看到的**： * CPU 使用率（分配资源的百分比） * 内存使用情况（MB/GB 随着时间的推移） * 磁盘使用情况（存储消耗） * 网络I/O（入口/出口） * 30 天的指标保留 ### 2\.配置自定义仪表板小部件添加和自定义指标小部件：指标选项卡 → 添加小部件 → 选择指标类型 **可用的小部件**： * 折线图（时间序列指标） * 条形图（部署比较） * 仪表（当前值） * 表格（多指标视图） **定制**： * 拖放式布局 * 可调时间范围（1小时、6小时、24小时、7天、30天） * 多副本聚合 * 图表上的部署标记 ### 3\.设置警报（需要专业计划）配置阈值违规警报：服务设置 → 警报 → 创建警报规则 **警报类型**： * CPU 阈值（例如，> 80% 持续 5 分钟） * 内存阈值（例如，> 90% 持续 10 分钟） * 磁盘使用率（例如，> 85%） * 自定义指标阈值 **通知渠道**： * 电子邮件（默认） * 不和谐网络钩子 * 松弛网络钩子 * 自定义 webhook（JSON 负载） ### 4\.集成外部 OTEL 收集器将指标导出到外部系统：服务设置 → 可观察性 → OTEL 集成 **配置环境变量**： OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318 OTEL_EXPORTER_OTLP_HEADERS=授权=承载<令牌> OTEL_SERVICE_NAME=我的铁路服务有关完整设置，请参阅“references/otel-integration.md”。 ### 5\.部署完整的 Grafana 堆栈使用 Railway 模板实现完整的可观察性： # 选项 1：通过铁路仪表板部署 # 模板 ID：8TLSQD（Grafana 堆栈） # 包括：Grafana、Prometheus、Loki、Tempo、Alloy # 选项 2：通过脚本部署 .claude/skills/railway-observability/scripts/deploy-grafana-stack.sh **堆栈组件**： * Grafana（可视化） * 普罗米修斯（指标） *洛基（日志） * 节奏（痕迹） * 合金（集电极） ## 工作流程 ### 第 1 步：访问内置指标 Railway 无需配置即可提供即时指标。 **导航至指标**：项目 → 服务 → 指标 **可用指标**： * CPU：使用百分比，分配的核心 * 内存：已使用的 MB，限制的百分比 * 磁盘：已使用 GB，读/写 IOPS * 网络：MB/s 入口/出口 **保留**：所有指标保留 30 天 ### 第 2 步：自定义仪表板创建个性化的监控视图。 **添加小部件**： 1. 点击“添加小部件” 2. 选择指标类型 3. 配置聚合 4. 设置时间范围 5. 通过拖放定位 **最佳实践**： * 组相关指标（CPU + 内存） * 使用部署标记进行关联 * 配置多副本视图 * 设置适当的时间范围 ### 步骤 3：配置警报（专业计划）设置主动监控。 **创建警报规则** : 服务→设置→警报→新规则 **警报配置**：指标：CPU 使用率条件：大于80% 持续时间：5 分钟通知：Slack Webhook **Webhook 负载示例**： { "service": "后端生产", “指标”：“cpu_使用情况”， “阈值”：80， “当前”：87.5， “时间戳”：“2025-11-26T10:30:00Z” } 有关所有警报类型，请参阅“references/dashboard-widgets.md”。 ### 步骤 4：整合 OTEL 出口商将指标发送到外部系统。 **配置合金收集器**： # 使用 templates/alloy-config.river 中的模板 # 部署为铁路服务 # 配置OTEL端点 **环境设置**： # 在您的铁路服务中 OTEL_EXPORTER_OTLP_ENDPOINT=http://合金:4318 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_METRICS_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp OTEL_TRACES_EXPORTER=otlp **验证集成**： # 检查合金日志铁路原木-S合金 # 应显示：“成功收到 OTLP 指标” 请参阅“references/otel-integration.md”以获取完整指南。 ### 步骤 5：部署 Grafana 可观测性堆栈铁路全程监控解决方案。 **部署堆栈**： # 运行部署脚本 cd .claude/技能/铁路可观测性/脚本 ./deploy-grafana-stack.sh # 或者通过 Railway Dashboard 手动部署 # 模板：8TLSQD（Grafana 堆栈） **堆栈包括**： * Grafana（端口 3000）- 仪表板 * Prometheus（端口 9090）- 指标存储 * Loki（端口3100）-日志聚合 * Tempo（端口 3200）- 分布式跟踪 *合金（端口4318）-OTLP收集器 **访问 Grafana** ：网址：https://.up.railway.app 用户名：管理员密码：（部署时设置） ## 架构 ### 渐进式披露结构 1. **SKILL.md**（此文件）：快速入门和工作流程 2. **references/** ：详细文档 * `metrics-reference.md` \- 完整的指标目录 * `dashboard-widgets.md` \- 小部件配置指南 * `otel-integration.md` \- 外部集成设置 3. **脚本/**：自动化工具 * `deploy-grafana-stack.sh` \- 部署可观察性堆栈 4. **templates/** ：配置文件 * `alloy-config.river` \- Grafana 合金收集器配置 ## 主要特点 ### 内置指标（始终可用）公制|描述 |单位 |保留率 ---|---|---|--- 中央处理器|已分配核心的百分比 |百分比 | 30天内存|内存使用情况 | MB/GB | 30天磁盘 |存储消耗|英国 | 30天网络输入/输出 |入口/出口流量 |兆字节/秒 | 30天 **无需配置** \- 自动收集所有服务的指标。 ### 仪表板定制 **拖放小部件**： *调整大小和重新定位 * 多种图表类型 * 自定义时间范围 * 部署标记 **多副本支持**： * 聚合视图（平均值、最小值、最大值、总和） * 每个副本的故障 * 副本缩放事件 **时间范围选项**： * 最后 1 小时 * 过去 6 小时 * 过去 24 小时 * 过去 7 天 * 过去 30 天 * 定制范围 ### 警报（仅限专业计划） **阈值警报**： * Y 分钟内 CPU > X% * 内存 > X MB 持续 Y 分钟 * 磁盘 > X% 容量 * 网络 > X MB/秒 **通知渠道**： # 电子邮件警报@example.com # Discord 网络钩子 https://discord.com/api/webhooks/... # Slack 网络钩子 https://hooks.slack.com/services/... # 自定义网络钩子 https://your-api.com/alerts **警报状态**： * 待处理（满足条件，等待时间） * 解雇（超过阈值） * 已解决（恢复正常） ### OTEL 整合 **支持的协议**： * OTLP/HTTP（端口 4318） * OTLP/gRPC（端口 4317） **信号类型**： * 指标（普罗米修斯格式） * 日志（JSON 结构） * 痕迹（Jaeger/Zipkin 格式） **收藏家选项**： * Grafana合金（推荐） * 打开遥测收集器 * 定制 OTLP 出口商 ## Grafana 堆栈详细信息 ### 模板部署 (8TLSQD) **一键部署** : 铁路仪表板 → 新建项目 → 部署模板 → 搜索“8TLSQD” **部署的服务**： 1.Grafana（可视化） 2. Prometheus（时序数据库） 3.Loki（日志聚合） 4. Tempo（轨迹存储） 5.合金（OTLP集电极） **配置**： * 预先配置的数据源 * 包括示例仪表板 * 持久存储卷 * 启用内部网络 ### 合金收集器 **用途**：从铁路服务接收 OTLP 信号并转发到 Grafana 堆栈。 **配置**（templates/alloy-config.river）： // OTLP接收器 otelcol.receiver.otlp“默认”{ grpc { 端点 =“0.0.0.0:4317” } http{ 端点 =“0.0.0.0:4318” } 输出{ 指标 = [otelcol.exporter.prometheus.default.input] 日志 = [otelcol.exporter.loki.default.input] 痕迹 = [otelcol.exporter.otlp.tempo.input] } } // 普罗米修斯导出器 otelcol.exporter.prometheus“默认”{ forward_to = [prometheus.remote_write.railway.receiver] } // Loki 导出器 otelcol.exporter.loki“默认”{ forward_to = [loki.write.railway.receiver] } // 速度导出器 otelcol.exporter.otlp“节奏”{ 客户{ 端点=“节奏：4317” } } ### Grafana 仪表板 **预建仪表板**： * 铁路服务指标（CPU、内存、磁盘、网络） * OTLP 指标概述 * 日志分析（洛基） * 轨迹浏览器（节奏） **自定义仪表板**： * 通过 Grafana UI 创建 * 从 Grafana.com 导入 * 使用 JSON 模型构建 ## 集成示例 ### 示例 1：监控 Node.js 服务 # 安装OTEL SDK npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node # 配置OTEL（在铁路服务中）导出 OTEL_EXPORTER_OTLP_ENDPOINT=http://合金:4318 导出 OTEL_SERVICE_NAME=nodejs-backend 导出 OTEL_METRICS_EXPORTER=otlp 导出 OTEL_LOGS_EXPORTER=otlp 导出 OTEL_TRACES_EXPORTER=otlp # 自动检测节点 --require @opentelemetry/auto-instrumentations-node/register app.js **在 Grafana 中查看**： * 指标：Grafana → 仪表板 → 铁路服务指标 * 日志：Grafana → 探索 → Loki * 痕迹：Grafana → 探索 → 节奏 ### 示例 2：内存不足警报 # 专业计划：服务 → 警报 → 新规则名称：内存不足警报指标：内存使用情况条件：大于 512 MB 持续时间：10 分钟通知：Slack Webhook Webhook URL：https://hooks.slack.com/services/YOUR/WEBHOOK/URL **松弛通知**： { "text": "🚨 高内存警报", “块”：[ { “类型”：“部分”， “文本”：{ “类型”：“mrkdwn”， "text": "*服务*：后端生产\n*内存*：567 MB（> 512 MB 阈值）\n*持续时间*：12 分钟" } } ] } ### 示例 3：来自 Python 的自定义指标从 opentelemetry 导入指标从 opentelemetry.sdk.metrics 导入 MeterProvider 从 opentelemetry.exporter.otlp.proto.http.metric_exporter 导入 OTLPMetricExporter # 配置 OTLP 导出器导出器 = OTLPMetricExporter( 端点=“http://alloy:4318/v1/metrics” ） # 创建计量提供者提供商 = MeterProvider(metric_readers=[ periodicexportingmetricreader（导出器，export_interval_millis = 60000） ]）指标.set_meter_provider（提供商） # 创建自定义指标仪表=metrics.get_meter(__name__) request_counter =meter.create_counter("api_requests_total") response_time =meter.create_histogram("api_response_time_seconds") # 记录指标 request_counter.add(1, {"endpoint": "/api/users", "method": "GET"}) response_time.record(0.125, {"endpoint": "/api/users"}) **在 Grafana 中查看**：探索 → Prometheus → 指标浏览器 → api_requests_total ## 交叉引用 * **railway-api** ：通过 GraphQL API 查询指标 * **railway-logs** ：日志聚合（补充指标） * **铁路部署** ：部署标记相关性 * **observability-stack-setup** ：本地 LGTM 堆栈（类似于 Railway 堆栈） ## 故障排除 ### 指标未显示 **检查服务状态**：铁路状态 -s <服务名称> **验证启用的指标**： * 指标始终启用 * 检查服务是否正在运行 * 等待 1-2 分钟获取第一个数据点 ### 警报未触发 **要求**： * 需要订阅专业计划 * 正确配置警报规则 * 在整个持续时间内满足条件 * 有效的通知渠道 **调试清单**： 1. 验证 Pro 计划是否有效 2. 检查阈值配置 3. 确认时长设置 4. 手动测试 webhook URL 5. 检查铁路仪表板的警报状态 ### OTEL 集成问题 **常见问题**： * 端点 URL 不正确 * 网络连接（使用内部铁路 URL） * 缺少身份验证标头 * 协议不匹配（HTTP 与 gRPC） **验证合金接收数据**： # 检查合金日志铁路原木-S合金 # 寻找： # ✅“OTLP 接收器已启动” # ✅“收到X个度量点” # ❌“连接被拒绝”=端点问题 # ❌“未经授权”= 身份验证问题有关详细的故障排除信息，请参阅“references/otel-integration.md”。 ## 最佳实践 ### 仪表板设计 1. 将相关指标分组（CPU + 内存在一起） 2. 使用部署标记来关联更改 3. 设置适当的时间范围（趋势为7天，事件为1小时） 4. 为不同的服务创建单独的仪表板 5. 使用多副本视图来扩展服务 ### 警报策略 1. 根据实际使用模式设置阈值 2. 使用持续时间避免误报（5-10 分钟） 3. 生产前测试通知渠道 4. 记录升级程序 5.定期审查和调整警报 ### OTEL 整合 1. 使用内部铁路 URL（无出口成本） 2.效率的批量指标（60秒间隔） 3.添加服务标签进行过滤 4. 对大量痕迹进行采样 5. 监控收集器资源使用情况 ### Grafana 堆栈 1.启用持久卷以保留数据 2.配置备份策略 3. 使用强密码保护 Grafana 4. 使用铁路内部网络 5.监控堆栈资源消耗 ## 快速参考 ### 访问可观察性 # 铁路仪表板 https://railway.app/project/<项目 ID>/service/<服务 ID>/metrics # 通过铁路 CLI 铁路状态 -s <服务名称> 铁路指标 -s <服务名称> ### 常见警报阈值公制|警告|关键 ---|---|--- 中央处理器| 70% | 90% 内存| 75% | 90% 磁盘 | 80% | 95% 网络| 80% 带宽 | 95% 带宽 ### OTEL 环境变量 OTEL_EXPORTER_OTLP_ENDPOINT=http://合金:4318 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_SERVICE_NAME=我的服务 OTEL_METRICS_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp OTEL_TRACES_EXPORTER=otlp ### Grafana 堆栈模板模板 ID：8TLSQD 组件：Grafana、Prometheus、Loki、Tempo、Alloy 部署：铁路仪表板→新建项目→部署模板费用：约 20-30 美元/月（取决于使用情况） ## 资源 * 铁路可观测性文档： * Grafana 模板： * OTEL 文档： * Grafana合金： ## 注释 * 内置指标对所有计划都是免费的 * 警报需要 Pro 计划（20 美元/月） * OTEL 集成适用于所有计划 * Grafana 堆栈部署为单独的 Railway 服务 * 指标保留 30 天 * 使用 OTEL 的内部铁路 URL（无出口费用） * 部署标记自动添加到图表中 * 多副本指标自动聚合 ** ** **更新**：2025 年 11 月 26 日 **模板 ID**：8TLSQD（Grafana 堆栈） **保留**：30 天（内置指标）

铁路可观测性

包含技能