Keep平台API开发实战指南：从设计理念到生产落地

Keep平台API开发实战指南从设计理念到生产落地【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keep一、API设计理念构建灵活的告警管理生态在现代运维体系中告警管理平台需要应对复杂多变的监控场景和多样化的工具链集成需求。Keep作为开源AIOps平台其API设计遵循三大核心原则为开发者提供既强大又易用的接口体系。资源抽象模型Keep将整个系统功能抽象为资源-操作-事件三层模型资源层包括告警(Alerts)、工作流(Workflows)、提供者(Providers)等核心实体操作层定义对资源的标准CRUD操作及业务逻辑处理事件层通过Webhook实现资源状态变更的实时通知这种设计使API具备高度一致性开发者只需掌握一套接口规范即可操作所有资源类型。例如无论是创建告警还是工作流都遵循相同的RESTful模式和认证机制。提供者架构设计Providers作为Keep的核心扩展机制采用标准化接口插件化实现架构使系统能灵活集成各类第三方服务。每个Provider实现以下标准接口# 核心接口定义keep/providers/base/base_provider.py class BaseProvider(ABC): abstractmethod def validate_config(self): 验证配置参数完整性和有效性 abstractmethod def dispose(self): 资源清理如关闭数据库连接 classmethod abstractmethod def get_available_actions(cls) - List[str]: 返回支持的操作列表这种设计确保了不同Provider的行为一致性同时允许每个Provider根据自身特性实现差异化功能。目前平台已支持130种Provider覆盖监控、通知、 ticketing等多个领域。图1Keep平台告警管理界面展示了基于API构建的告警监控与分类系统二、实战开发流程从环境搭建到接口调用开发环境准备1. 源码获取git clone https://gitcode.com/GitHub_Trending/kee/keep cd keep2. 本地部署# 使用Docker Compose快速启动 docker-compose up -d3. API密钥生成通过UI界面生成API Key登录系统后进入Settings → API Keys点击Generate New Key设置权限范围保存生成的API Key后续所有请求需包含此密钥核心API调用示例认证机制所有API请求必须在HTTP头部包含认证信息GET /api/v1/alerts HTTP/1.1 Host: localhost:8080 Authorization: Api-Key your_api_key1. 告警查询接口import requests API_KEY your_api_key BASE_URL http://localhost:8080/api/v1 headers { Authorization: fApi-Key {API_KEY}, Content-Type: application/json } # 查询严重级别为critical的活跃告警 params { status: firing, severity: critical, limit: 10 } response requests.get(f{BASE_URL}/alerts, headersheaders, paramsparams) alerts response.json() for alert in alerts[alerts]: print(f告警ID: {alert[fingerprint]}, 名称: {alert[name]})2. 工作流创建接口# 创建CPU使用率过高自动告警工作流 workflow_data { name: high-cpu-remediation, description: 当CPU使用率超过阈值时自动通知并执行 remediation, trigger: { type: alert, conditions: [ { field: severity, operator: equals, value: critical }, { field: name, operator: contains, value: High CPU Usage } ] }, actions: [ { provider: slack-provider, type: notify, channel: #alerts, message: CPU使用率超过阈值: {{ alert.value }}% }, { provider: kubernetes-provider, type: scale_deployment, namespace: production, deployment: app-server, replicas: {{ alert.value 90 ? 3 : 2 }} } ] } response requests.post( f{BASE_URL}/workflows, headersheaders, jsonworkflow_data ) if response.status_code 201: print(f工作流创建成功ID: {response.json()[id]}) else: print(f创建失败: {response.text})三、自定义Provider开发扩展平台能力边界当现有Provider无法满足业务需求时开发者可以通过自定义Provider扩展平台能力。以下是开发自定义Provider的完整流程。开发步骤1. 创建Provider目录结构keep/providers/yourcompany_provider/ ├── __init__.py ├── yourcompany_provider.py └── README.md2. 实现Provider类# keep/providers/yourcompany_provider/yourcompany_provider.py from dataclasses import dataclass from keep.providers.base.base_provider import BaseProvider from keep.providers.models.provider_config import ProviderConfig dataclass class YourcompanyProviderAuthConfig: api_key: str dataclasses.field( metadata{required: True, sensitive: True, description: API访问密钥} ) api_endpoint: str dataclasses.field( metadata{required: True, description: API服务端点URL} ) class YourcompanyProvider(BaseProvider): PROVIDER_DISPLAY_NAME YourCompany Monitoring PROVIDER_CATEGORY [monitoring, logging] def __init__(self, provider_id: str, config: ProviderConfig): super().__init__(provider_id, config) self.auth_config YourcompanyProviderAuthConfig(**self.config.authentication) self.client self._init_client() def _init_client(self): 初始化API客户端 import requests session requests.Session() session.headers.update({Authorization: fBearer {self.auth_config.api_key}}) return session def validate_config(self): 验证配置有效性 try: response self.client.get(f{self.auth_config.api_endpoint}/health) response.raise_for_status() return True except Exception as e: self.logger.error(f配置验证失败: {str(e)}) raise def query_metrics(self, query: str, start_time: str, end_time: str): 查询监控指标数据 params { query: query, start: start_time, end: end_time } response self.client.get( f{self.auth_config.api_endpoint}/metrics, paramsparams ) return response.json() def dispose(self): 清理资源 self.client.close()3. 注册Provider# keep/providers/yourcompany_provider/__init__.py from .yourcompany_provider import YourcompanyProvider, YourcompanyProviderAuthConfig __all__ [YourcompanyProvider, YourcompanyProviderAuthConfig]4. 本地测试# 测试代码示例 from keep.providers.yourcompany_provider.yourcompany_provider import YourcompanyProvider from keep.providers.models.provider_config import ProviderConfig config ProviderConfig( authentication{ api_key: your_test_key, api_endpoint: https://api.yourcompany.com } ) provider YourcompanyProvider(yourcompany-provider, config) provider.validate_config() metrics provider.query_metrics( avg(cpu_usage), 2023-01-01T00:00:00Z, 2023-01-01T01:00:00Z ) print(metrics)打包与分发开发完成后可通过两种方式集成自定义Provider直接提交PR到Keep主仓库推荐通过Python包管理器安装为独立插件四、性能调优策略提升API调用效率在大规模部署场景中API性能直接影响系统响应速度和资源消耗。以下是经过实践验证的性能优化策略。请求优化1. 批量操作接口对于需要处理多个资源的场景优先使用批量接口POST /api/v1/alerts/batch Content-Type: application/json { operations: [ {action: update, id: alert1, status: resolved}, {action: update, id: alert2, status: resolved} ] }2. 字段过滤通过fields参数指定返回字段减少数据传输量GET /api/v1/alerts?fieldsid,name,status,severity3. 分页与游标处理大量数据时使用分页参数GET /api/v1/alerts?limit50offset100对于频繁滚动查询使用游标分页GET /api/v1/alerts?limit50cursoreyJpZCI6MTIzfQ服务端优化1. 缓存策略利用ETag实现条件请求GET /api/v1/workflows/123 If-None-Match: abc1232. 异步处理对于耗时操作使用异步接口POST /api/v1/workflows/123/execute Accept: application/json Prefer: respond-async { parameters: {immediate: true} }响应HTTP/1.1 202 Accepted X-Request-ID: req-123456 Location: /api/v1/requests/req-123456随后通过X-Request-ID查询执行状态GET /api/v1/requests/req-123456图2告警表格展示了API查询结果的分页与排序功能支持高效数据浏览五、常见问题诊断与解决方案认证与授权问题症状API请求返回401或403错误排查步骤检查API Key是否正确可通过以下接口验证GET /api/v1/auth/validate Authorization: Api-Key your_api_key确认API Key权限范围通过UI检查是否包含所需操作权限检查请求头格式是否正确确保使用Api-Key前缀解决方案# 权限不足时重新生成包含所需权限的API Key response requests.post( f{BASE_URL}/api-keys, headersheaders, json{ name: new-key, permissions: [alerts:read, workflows:write] } ) new_key response.json()[key]性能瓶颈症状API响应时间超过500ms排查工具 使用平台内置的API性能监控GET /api/v1/monitoring/api-performance常见解决方案优化查询条件添加适当过滤增加缓存层特别是对于静态数据对大结果集使用分页和字段过滤版本迁移当API版本升级时可通过以下策略平滑迁移版本共存新API使用版本前缀如/api/v2旧版本保持兼容弃用通知响应头中包含弃用信息Deprecation: true Sunset: 2023-12-31T00:00:00Z Link: https://api.keep.com/api/v2/alerts; relsuccessor-version迁移工具使用scripts/migrate_api_calls.py自动转换旧API调用六、生态扩展路径构建API驱动的告警自动化体系Keep API不仅是接口集合更是构建完整告警管理生态的基础。以下是几种典型的扩展方向与AI/ML集成利用API将告警数据导入机器学习平台构建智能告警分类模型# 导出历史告警数据用于模型训练 response requests.get( f{BASE_URL}/api/v1/alerts/export, headersheaders, params{start_date: 2023-01-01, end_date: 2023-06-01} ) with open(alerts_training_data.json, w) as f: f.write(response.text)图3AI工作流助手界面展示了如何通过自然语言描述自动生成API调用流程自定义仪表板基于API构建业务定制的监控仪表板// 前端示例定期获取并更新告警统计数据 async function updateAlertStats() { const response await fetch(/api/v1/alerts/stats, { headers: { Authorization: Api-Key apiKey } }); const stats await response.json(); // 更新图表数据 cpuChart.update(stats.cpu_alerts); memoryChart.update(stats.memory_alerts); } // 每30秒更新一次 setInterval(updateAlertStats, 30000);跨平台集成通过API实现与其他运维工具的无缝集成CI/CD管道在部署流程中调用API创建维护窗口工单系统告警触发时自动创建支持工单知识库将告警与相关文档自动关联总结Keep API为开发者提供了构建灵活、强大的告警管理解决方案的基础。通过本文介绍的设计理念、开发流程和优化策略技术团队可以充分利用平台能力实现从告警检测到自动修复的全流程闭环。最佳实践在开始API集成前建议先熟悉docs/overview/introduction.md中的核心概念然后参考examples/workflows/目录下的示例代码快速启动项目。对于复杂场景可结合自定义Provider和Webhook实现深度集成。随着平台的持续演进API将支持更多高级特性包括AI辅助告警分析、跨云环境统一监控等功能。开发者可通过贡献代码参与API功能的开发与改进共同构建更完善的开源AIOps生态。【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考