可观测性后端微服务云原生【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sky/skywalking点击查看免费下载本文基于 Apache SkyWalking OAPObservability Analysis Platform核心模块系统讲解如何通过自定义Source数据源与Scope作用域来扩展全新的指标类型。读者将掌握 SourceReceiver 的注入机制、ScopeDeclaration与ScopeDefaultColumn注解的完整用法、getEntityId()在 OAL group 机制中的作用以及如何将新 Scope 注册进 OAL 语法OALLexer.g4/OALParser.g4最终独立实现从接收原始指标数据 → 构建 Source → 编写 OAL 脚本 → 重打包的完整扩展链路。Source 与 Scope一对相互关联的核心概念在动手写代码之前必须先厘清两个经常被混用的概念。根据 OAL scope 介绍Scope声明了 IDint 类型和名称而Source则声明了一组具体属性attributes。二者是一一对应的关系Scope本质是一个指标归类标签。例如Service、ServiceInstance、Endpoint它们在 OAL 脚本中表现为from(Service.latency)中的Service。Source是承载指标原始数据的 Java 类其属性如latency、status、responseCode会作为 OAL 脚本中可引用的字段最终参与指标聚合计算。在仓库中这一关系体现在 ScopeDeclaration.java 的注解定义上注解中的id()与name()对应 Scope 的 ID 与名称而标注了该注解的 Source 类则通过自身字段声明属性。此外该注解还支持catalog()参数用于声明顶层 Scope 名称定义于Scope枚举当生成的指标需要支持告警alerting时使用非指标类 Source 可留空字符串。所有分析数据都必须是对 Source.java 抽象类的继承并落在org.apache.skywalking包下才能被 OAL 脚本引擎与 OAP 核心支持。Source抽象类本身只做了一件事持有timeBucket时间桶字段用于指标按时间窗口聚合。SourceReceiverOAP 核心的指标注入入口OAP 核心模块oap-server/server-core提供了一个内部服务接口SourceReceiver它是所有 Source 数据进入分析管线的统一入口public interface SourceReceiver extends Service { void receive(ISource source); }注意当前仓库实现中receive的入参类型为ISource接口见 SourceReceiver.java此外还额外暴露了getDispatcherDetectorListener()方法用于监听 Dispatcher 的注册事件。ISource.java 定义了所有 Source 必须实现的契约public interface ISource { int scope(); // 返回该 Source 所属的 Scope ID long getTimeBucket(); // 获取时间桶 void setTimeBucket(long timeBucket); // 设置时间桶 String getEntityId(); // 返回实体唯一 ID default void prepare() {} // dispatch 前的内部数据准备钩子 }prepare()是一个默认空实现的可选钩子在 SourceDispatcher#dispatch(ISource) 调用之前执行适合做一些字段预处理。其默认实现 SourceReceiverImpl.java 展示了数据流转的核心逻辑public class SourceReceiverImpl implements SourceReceiver { private final DispatcherManager dispatcherManager; Override public void receive(ISource source) { dispatcherManager.forward(source); } public void scan() throws IOException, InstantiationException, IllegalAccessException { dispatcherManager.scan(); } }从源码可以清晰地看到receive()将 Source 转交给DispatcherManager由其根据 Source 的 scope ID 转发给对应的SourceDispatcher。DispatcherManager通过scan()扫描org.apache.skywalking包下所有带注册注解的 Source 与 Dispatcher这解释了为什么 Source 类必须位于该包路径下。编写自定义 Source 类以 ServiceInstance 为模板下面以仓库中现成的 ServiceInstance.java 为例逐段拆解自定义 Source 的写法ScopeDeclaration(id SERVICE_INSTANCE, name ServiceInstance, catalog SERVICE_INSTANCE_CATALOG_NAME) ScopeDefaultColumn.VirtualColumnDefinition(fieldName entityId, columnName entity_id, isID true, type String.class) public class ServiceInstance extends Source { Override public int scope() { return DefaultScopeDefine.SERVICE_INSTANCE; } Override public String getEntityId() { return String.valueOf(id); } Getter Setter private int id; Getter Setter ScopeDefaultColumn.DefinedByField(columnName service_id) private int serviceId; Getter Setter private String name; Getter Setter private String serviceName; Getter Setter private String endpointName; Getter Setter private int latency; Getter Setter private boolean status; Getter Setter private int responseCode; Getter Setter private RequestType type; }scope() 方法ID 必须与 ScopeDeclaration 一致scope()方法返回的 ID 不是随机值它必须在ScopeDeclaration注解中同步声明并且两者必须完全一致。例如ServiceInstance的scope()返回DefaultScopeDefine.SERVICE_INSTANCE而注解中写的也是id SERVICE_INSTANCE常量来自 DefaultScopeDefine.java。OAP 核心正是凭借这个 ID 完成Source → Dispatcher → 持久化实体的映射任何不一致都会导致数据无法被正确分发。getEntityId()实体唯一标识与 OAL group 机制getEntityId()的返回值代表该 Scope 关联的唯一实体。以 Service 为例它就是 service ID代表一个具体的服务例如Order服务。该值被用于 OAL group 机制当 OAL 脚本中按实体进行分组聚合时如按服务分组求平均响应时间不同实体的数据正是靠entityId区隔开的。因此自定义 Source 时务必设计好什么是一个实体并让getEntityId()稳定地返回其标识。ScopeDefaultColumn默认列声明ScopeDefaultColumn.VirtualColumnDefinition与ScopeDefaultColumn.DefinedByField是必选项二者声明的所有字段都会被推入持久化实体映射为存储层中的列——例如 ElasticSearch 索引的字段、数据库表的列。从 ScopeDefaultColumn.java 的源码看两者分工明确注解标注位置核心参数说明VirtualColumnDefinition类TYPEfieldName、columnName、type、isID、length声明虚拟列。isID true时表示该列即实体 ID其取值来自ISource#getEntityId()的返回值典型场景下指标 ID 时间戳 实体 ID。length仅对 String 类型生效默认 512DefinedByField字段FIELDcolumnName、requireDynamicActive、length、groupByCondInTopN声明实体字段直接映射为列。requireDynamicActive为 true 时该列仅在核心配置core/activeExtraModelColumns true时才会被加入生成的指标模型groupByCondInTopN自 9.5.0 起表示该列是否作为 TopN 聚合的 groupBy 条件以ServiceInstance为例entityId通过VirtualColumnDefinition虚拟列声明isID true映射列名entity_id而serviceId通过DefinedByField声明映射列名service_id。这些默认列会被 OAL Runtime 自动检测并且在查询阶段是必需的——这也是为什么 service 实例级别的 Scope 通常都会包含 entity ID 与 service ID。在动手前建议通读现有所有 Scope 的写法作为参照位于 source 包目录 下如Service、Endpoint、DatabaseAccess、CacheAccess、MQAccess、K8SService、CiliumService等数十个现成范例。将 Scope 注册进 OAL 语法文件仅定义 Source 类还不够为了让新 Scope 能在 OAL 脚本中被from(ScopeName.attr)引用还必须修改 OAL 的 ANTLR 语法定义。语法文件位于oal-grammar模块的antlr4目录下词法文件 OALLexer.g4以关键字形式加入 Scope 名称例如现有定义SRC_SERVICE: Service; SRC_SERVICE_INSTANCE: ServiceInstance; SRC_ENDPOINT: Endpoint; SRC_DATABASE_ACCESS: DatabaseAccess; SRC_CACHE_ACCESS: CacheAccess; SRC_MQ_ACCESS: MQAccess;语法文件 OALParser.g4在source产生式中追加对应的 token。现有规则将全部 scope 关键字用|连接source : SRC_SERVICE | SRC_TCP_SERVICE | SRC_DATABASE_ACCESS | SRC_SERVICE_INSTANCE | SRC_SERVICE_RELATION | ... | SRC_BROWSER_APP_PERF | ... ;两个文件都必须修改缺一不可Lexer 负责把脚本中的ServiceInstance识别成 tokenParser 负责将该 token 组合进source语法树节点。完成修改后新 Scope 即可在 OAL 脚本中合法出现。构建 Receiver让数据真正流动起来完成 Source 与语法注册后还差最后一块拼图——Receiver它负责完成三件事获取指标的原始数据从 Agent 上报、第三方系统推送或消息队列如 Kafka中读取原始指标数据构建 Source 并注入SourceReceiver将原始数据填充进自定义 Source 对象调用sourceReceiver.receive(source)送入分析管线编写 OAL 脚本并重打包为聚合逻辑补充 OAL 脚本然后重新打包项目使改动生效。关于第 2 步仓库中的 receiver 插件提供了大量现成调用范例。例如 MultiScopesErrorLogAnalysisListener.java 在一次构建中连续注入多个 SourceOverride public void build() { sourceReceiver.receive(sourceBuilder.toBrowserAppTraffic()); sourceReceiver.receive(sourceBuilder.toBrowserAppSingleVersionTraffic()); sourceReceiver.receive(sourceBuilder.toBrowserAppPageTraffic()); }而 ErrorLogRecordListener.java 则展示了带采样判断的注入方式——只有SampleStatus.SAMPLED的样本才调用sourceReceiver.receive(errorLog)。这些监听器通常实现AnalysisListener接口parse()阶段把原始数据逐字段填入 Source如sourceBuilder.setService(...)、setServiceVersion(...)build()阶段统一完成注入这样 Source 的字段声明与实际填充逻辑一一对应便于追踪数据链路。值得留意的是SkyWalking 已内置了覆盖 Trace、JVM、CLR、Browser、K8s、Cilium、Envoy、MQ、Cache、Database、日志等场景的几十种 Source可对照 source 包目录 与 OALLexer.g4 中的关键字列表绝大多数需求都可直接复用现有 Scope 而无需新增。仅在现有 Scope 无法表达新指标语义时才需要按本文流程做完整扩展。完整扩展步骤速查在org.apache.skywalking.oap.server.core.source包中新建 Source 类继承Source用ScopeDeclaration声明 Scope ID 与名称用ScopeDefaultColumn声明默认列实现scope()返回与ScopeDeclaration.id一致的 ID参照DefaultScopeDefine常量实现getEntityId()返回稳定的实体唯一标识供 OAL group 机制使用在 OALLexer.g4 中加入 Scope 名称关键字在 OALParser.g4 的source产生式中注册该 token构建 Receiver获取原始数据 → 构建 Source → 调用sourceReceiver.receive(source)可参考skywalking-browser-receiver-plugin等插件的监听器实现补充 OAL 脚本定义聚合指标重新打包项目。完成以上步骤后新指标即可像内置指标一样被 OAL 计算、落库并通过查询协议对外提供成为 SkyWalking 分析体系的原生组成部分。赞分享可观测性后端微服务云原生【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sky/skywalking点击查看免费下载相关推荐ROG笔记本色彩异常诊断与修复G-Helper专业解决方案ROG笔记本色彩异常诊断与修复G Helper专业解决方案 当你的ROG游戏本屏幕色彩失真、色调异常或GameVisual显示模式切换失效时这通常不是硬件故可观测性后端微服务云原生CreamInstaller终极指南三步轻松解锁Steam、Epic、Ubisoft游戏DLCCreamInstaller终极指南三步轻松解锁Steam、Epic、Ubisoft游戏DLC 还在为游戏DLC的高昂价格烦恼吗想要体验完整游戏内容却不想花桌面应用Apache APISIX skywalking-logger 插件接入 SkyWalking OAP 的访问日志上报实战指南Apache APISIX skywalking logger 插件接入 SkyWalking OAP 的访问日志上报实战指南 导读 skywalking l后端微服务云原生上一篇【亲测免费】 Cursor Fake Machine 项目使用教程下一篇B23Downloader开源项目使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考