可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载导读本文聚焦 Apache SkyWalking 后端OAP Server中负责指标定义与动态编译的核心组件——OALObservability Analysis LanguageV2 引擎源码位于 oap-server/oal-rt。OAL 是 SkyWalking 自研的可观测性分析语言运维人员通过编写.oal脚本即可声明式地定义监控指标如服务响应时间、SLA、CPM、百分位等OAL 引擎则在 OAP 启动时把脚本实时编译为可直接挂入流处理管线的 Java 字节码。读完本文你将掌握 OAL V2 引擎的完整流水线解析 → 元数据富化 → 字节码生成、不可变数据模型与设计原则、两级调试开关的使用方法以及引擎与 server-core 的解耦加载机制并能结合仓库源码与真实 OAL 脚本直接上手排查与二次开发。一、OAL V2 引擎是什么唯一且独立的 OAL 实现在 Apache SkyWalking 中OALObservability Analysis Language用于定义从监控数据源Source如Service、ServiceRelation、Endpoint中聚合出的指标。根据 oap-server/oal-rt/CLAUDE.md 的定位说明oal-rt模块承载的 OAL V2 Engine 是当前仓库中唯一的 OAL 实现This is the only OAL implementation它使用 V2 解析器基于 ANTLR产出不可变模型解析 OAL 脚本使用MetricDefinitionEnricher通过反射为模型补充元数据使用OALClassGeneratorV2基于Javassist FreeMarker 模板在运行时生成 Java 类。引擎入口类为 OALEngineV2.java其类注释明确列出了三项职责与核心收益使用 V2 解析器解析 OAL 脚本不可变模型使用MetricDefinitionEnricher富化 V2 模型元数据使用 V2 模板OALClassGeneratorV2生成类。同时强调其收益清晰的不可变数据模型、类型安全的过滤值与函数参数、带源码位置追踪的更好错误信息、完全独立无 V1 代码依赖。1.1 真实 OAL 脚本长什么样OAP 内置了多份真实 OAL 脚本位于 oap-server/server-starter/src/main/resources/oal 目录下包括core.oal、browser.oal、java-agent.oal、mesh.oal、ebpf.oal、cilium.oal、virtual-gen-ai.oal等。以 core.oal 为例// Service scope metrics service_resp_time from(Service.latency).longAvg().decorator(ServiceDecorator); service_sla from(Service.*).percent(status true).decorator(ServiceDecorator); service_cpm from(Service.*).cpm().decorator(ServiceDecorator); service_percentile from(Service.latency).percentile2(10); // p50, p75, p90, p95, p99 service_apdex from(Service.latency).apdex(name, status).decorator(ServiceDecorator); service_mq_consume_count from(Service.*).filter(type RequestType.MQ).count(); service_mq_consume_latency from((str-long)Service.tag[transmission.latency]) .filter(type RequestType.MQ).filter(tag[transmission.latency] ! null).longAvg(); // Service relation scope metrics for topology service_relation_client_cpm from(ServiceRelation.*).filter(detectPoint DetectPoint.CLIENT).cpm(); service_relation_server_resp_time from(ServiceRelation.latency).filter(detectPoint DetectPoint.SERVER).longAvg();可以看到 OAL 的典型语法结构指标名 from(Source.属性).filter(条件).聚合函数(参数)支持decorator装饰器、filter过滤含枚举比较、Map 取值tag[key]、类型转换(str-long)以及percentile2(10)这类多值聚合函数。这些脚本正是 V2 引擎每次启动时的真实输入。二、包结构四个职责清晰的子包根据 CLAUDE.md 的包结构说明已与源码 oal-rt 主源码目录 逐一核对org.apache.skywalking.oal.v2/ ├── model/ # 不可变数据模型解析器输出 │ ├── SourceLocation # 源文件位置用于错误报告 │ ├── SourceReference # from(Service.latency) │ ├── FunctionCall # longAvg(), percentile2(10) │ ├── FunctionArgument # 类型化函数参数 │ ├── FilterOperator # 枚举: , !, , , like, in │ ├── FilterExpression # latency 100 │ ├── FilterValue # 类型化过滤值 │ └── MetricDefinition # 完整解析后的指标 ├── parser/ # OAL 脚本解析 │ ├── OALListenerV2 # ANTLR 解析树监听器 │ └── OALScriptParserV2 # 解析器门面 ├── generator/ # 代码生成 │ ├── CodeGenModel # 代码生成数据模型 │ ├── MetricDefinitionEnricher # 元数据富化 │ └── OALClassGeneratorV2 # Javassist 字节码生成器 ├── metadata/ # Source/指标元数据工具 │ ├── SourceColumnsFactory │ ├── SourceColumn │ ├── FilterMatchers │ └── MetricsHolder ├── util/ # 代码生成工具 │ ├── ClassMethodUtil │ └── TypeCastUtil └── OALEngineV2 # 主引擎入口每个子包的职责边界非常清晰model纯数据模型只承载一条 OAL 语句解析后是什么不含任何生成逻辑parser把.oal文本变成MetricDefinition列表generator把富化后的CodeGenModel变成可加载的 Java 类metadata负责从 Source 类、Metrics 类上反射抽取列信息、匹配器信息util方法名拼接getter/setter、类型转换等辅助工具。2.1 过滤器运算符全集model包下的 FilterOperator.java 定义了 OAL 支持的全部过滤运算符运算符枚举值匹配器类型适用值类型EQUALequal数值/字符串/布尔/枚举!NOT_EQUALnotEqual数值/字符串/枚举/nullGREATERgreater数值LESSless数值GREATER_EQUALgreaterEqual数值LESS_EQUALlessEqual数值likeLIKElike字符串inINin数组containCONTAINcontain字符串not containNOT_CONTAINnotContain字符串结合 MetricDefinitionEnricher.java 中的mapOperatorToExpressionType方法可以看到完整的映射关系布尔值映射到booleanMatch/booleanNotEqualMatch数值映射到numberMatch/greaterMatch/lessMatch等字符串映射到stringMatch/likeMatch/containMatch数组映射到inMatch枚举比较则复用字符串匹配器如type RequestType.MQ。三、核心流水线Parser → Enricher → GeneratorCLAUDE.md 给出了整个引擎的三段式流水线┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ .oal file │───▶│ Parser │───▶│ Enricher │───▶│ Generator │ │ │ │ │ │ │ │ │ │ OAL script │ │ MetricDef │ │ CodeGenModel│ │ Bytecode/ │ │ │ │ (immutable) │ │ (metadata) │ │ Source │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ParserOALScriptParserV2把.oal文件解析为不可变的MetricDefinition对象EnricherMetricDefinitionEnricher通过反射补充元数据Source 列、持久化字段GeneratorOALClassGeneratorV2使用 Javassist 和 FreeMarker 模板生成 Java 类。3.1 入口调用链OALEngineV2.start()OALEngineV2.start() 完整实现了上述流水线try (Reader reader ResourceUtils.read(oalDefine.getConfigFile())) { // 1. 解析 OALScriptParserV2 v2Parser OALScriptParserV2.parse(reader, oalDefine.getConfigFile()); // 2. 富化 ListCodeGenModel codeGenModels enrichMetrics(v2Parser.getMetrics()); // 3. 生成 classGeneratorV2.generateClassAtRuntime( codeGenModels, v2Parser.getDisabledSources(), metricsClasses, dispatcherClasses); }启动日志会依次输出解析成功了多少条指标、富化了多少条、最终生成了多少 metrics 类与 dispatcher 类V2 Parser: Successfully parsed N metrics V2 Enricher: Enriched N metrics with metadata OAL Engine V2 started successfully. Generated X metrics classes, Y dispatcher classes3.2 阶段一Parser —— ANTLR 解析树到不可变模型OALScriptParserV2.java 展示了解析流程用OALLexer由 oal-grammar 模块的 ANTLR 语法 生成做词法分析用OALParser做语法分析挂载自定义的OALErrorListener收集带文件名与位置的详细错误信息若有语法错误直接抛出IllegalArgumentException错误信息含源码位置用ParseTreeWalker驱动OALListenerV2遍历解析树产出MetricDefinition列表与disabledSources列表。OALListenerV2在遍历聚合语句exitAggregationStatement时会通过 ANTLR 的Interval 切片把每条指标语句的原文、from(...)片段、聚合函数片段、过滤片段逐字byte-for-byte记录下来供 dsl-debugging 使用详见下文调试输出部分。解析器同时支持直接从字符串解析parse(String script)这在单元测试中非常有用——OALScriptParserV2Test 与 RealOALScriptsTest 就分别覆盖了语法单元测试与真实脚本解析测试。3.3 阶段二Enricher —— 反射注入元数据MetricDefinitionEnricher.enrich() 的八步处理通过MetricsHolder.find(聚合函数名)查找到对应的指标函数类如LongAvgMetrics通过SourceColumnsFactory.getColumns(Source名)获取 Source 类的列元数据字段名、列名、类型、是否 ID、是否分片键等通过DefaultScopeDefine.valueOf(Source名)得到 Source 的 scopeId查找Entrance注解标注的入口方法沿类继承链向上搜索遍历入口方法参数按SourceFrom、ConstOne、Expression、Arg、DefaultValue注解生成对应的参数表达式与参数类型LITERAL_TYPE1、ATTRIBUTE_EXP_TYPE2、EXPRESSION_TYPE3从 Metrics 类收集Column注解的持久化字段按类型生成序列化字段分组int/double/String/long/复杂对象把过滤表达式转换为模板格式含匹配器类名、左右操作数表达式、原文切片。这一步是模型与生成之间的桥梁产出的 CodeGenModel 成为 FreeMarker 模板的数据输入。3.4 阶段三Generator —— Javassist 运行时生成三类类OALClassGeneratorV2.generateClassAtRuntime() 每个指标生成三类类Metrics 类如ServiceRespTimeMetrics继承自父指标类如LongAvgMetrics动态添加 Source 字段带Column、BanyanDB.SeriesID、ElasticSearch.EnableDocValues等注解、无参构造器并从模板生成id、hashCode、remoteHashCode、equals、serialize、deserialize、getMeta、toHour、toDay、appendDebugFields等方法最后打上Stream注解含表名、scopeId、builder 类、processor 类Metrics Builder 类如ServiceRespTimeMetricsBuilder实现存储层 Builder 接口从存储模块指定的模板路径生成entity2Storage、storage2Entity两个方法因此不同存储ES/BanyanDB可提供不同的 builder 模板Dispatcher 类如ServiceDispatcher按 Source 分组一个 Source 对应一个 dispatcher实现SourceDispatcherSource接口为每个指标生成doMetric()方法外加统一的dispatch()分发方法。模板方面V2 引擎使用独立的模板目录/code-templates-v2见 OALClassGeneratorV2 构造器与 V1 模板完全隔离。生成完成后引擎把 metrics 类与 dispatcher 类分别通知给StreamAnnotationListener注册为流处理器和DispatcherDetectorListener注册为 Source 分发器从而接入 SkyWalking 的流处理管线见 OALEngineV2.notifyAllListeners()。四、设计原则为何 V2 采用不可变模型CLAUDE.md 明确列出了 V2 引擎的五条设计原则这些原则在源码中均有落实不可变模型Immutable Models所有解析器输出类不可变且线程安全。以 MetricDefinition.java 为例类被声明为public final class所有字段private final列表字段在构造时通过Collections.unmodifiableList(new ArrayList(...))防御性拷贝实例只能通过Builder构建。类型安全Type Safety用枚举与类型化值替代裸字符串。过滤值由 FilterValue 统一封装区分数值/字符串/布尔/null/枚举/数组运算符是FilterOperator枚举而非字符串。Builder 模式Builder Pattern复杂对象全部使用流式 Builder。MetricDefinition、SourceReference、FilterExpression、FunctionCall均内置Builder内部类。关注点分离Separation of Concerns解析模型 ≠ 代码生成模型。MetricDefinition解析输出与CodeGenModel生成输入是两个独立类中间由 Enricher 转换。可测试性Testability模型可以不经过解析直接手工构造便于单元测试。例如 FilterExpressionTest、FunctionCallTest 都是直接构造模型实例进行断言。4.1 关键类一MetricDefinition解析输出CLAUDE.md 给出了一个可以直接运行的构造示例对应 OALservice_resp_time from(Service.latency).filter(latency 0).longAvg()MetricDefinition metric MetricDefinition.builder() .name(service_resp_time) .source(SourceReference.of(Service, latency)) .addFilter(FilterExpression.of(latency, , 0L)) .aggregationFunction(FunctionCall.of(longAvg)) .build();MetricDefinition携带的字段包括name指标名、tableName存储表名缺省等于 name、sourceSource 引用、filters过滤表达式列表、aggregationFunction聚合函数、decorator装饰器、location源码位置、sourceText整条语句原文与fromTextfrom(...)片段原文。其中后两者是 ANTLR Interval 切片的结果专门服务于 dsl-debugging 的逐字匹配。SourceReference见 SourceReference.java支持三种形态from(Service.latency) // nameService, attributelatency from(Service.*) // nameService, 通配 from((long)Service.tag[key]) // nameService, attributetag[key], castTypelong4.2 关键类二CodeGenModel生成输入CodeGenModel是 Enricher 的产物供模板与 Javassist 消费。CLAUDE.md 给出了其核心访问方式// Created by MetricDefinitionEnricher CodeGenModel model enricher.enrich(metricDefinition); // Contains: source columns, persistent fields, metrics class info, etc. model.getFieldsFromSource(); // 从 Source 拷贝的字段 model.getPersistentFields(); // 用于存储的字段 model.getMetricsClassName(); // 例如 LongAvgMetrics从 MetricDefinitionEnricher.enrich() 可以看到完整的 CodeGenModel 组成varName、metricsNamesnake_case 转 PascalCase、tableName、sourceName、sourceScopeId、from含 fromText、functionName、aggregationSourceText、sourceLine、metricSourceText、metricsClassName、filters、fieldsFromSource、persistentFields、serializeFields、entranceMethod、sourceDecorator。所有与 dsl-debugging 相关的原文切片字段fromText、aggregationSourceText、metricSourceText都由解析器在 ANTLR Interval 切片阶段捕获代码生成阶段不需要做任何运行时重建。五、调试输出两个独立的环境变量开关CLAUDE.md 着重介绍了 OAL 引擎的调试机制——通过两个相互独立的环境变量控制环境变量作用SW_DYNAMIC_CLASS_ENGINE_DEBUGtrue控制磁盘转储把生成的.class文件写入磁盘SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue控制代码生成分支切换为带调试探针的模板5.1 SW_DYNAMIC_CLASS_ENGINE_DEBUG转储 class 与配套 java 源文件在 OALClassGeneratorV2 构造器 中openEngineDebug StringUtil.isNotEmpty(System.getenv(SW_DYNAMIC_CLASS_ENGINE_DEBUG))读取该变量。开启后生成的.class会写入磁盘且每个.class都会配对一个ClassName.java生成源码文件——即 Javassist 编译时输入的确切 Java 源码synthetic{skywalking}/oal-rt/ ├── metrics/ │ ├── ServiceRespTimeMetrics.class │ └── ServiceRespTimeMetrics.java ← Javassist compile input (synthetic) └── dispatcher/ ├── ServiceRelationDispatcher.class └── ServiceRelationDispatcher.java配套.java文件存在的意义非常实际Javassist 产出的字节码经常让反编译器如 FernFlower困惑——没有goto合并、混合类型的槽位复用、调试注入的if (gate.isGateOn()) { ... }链FernFlower 常常直接退化为 compiled code 存根。而.java源文件可以让 IDE 的 source-attach 直接渲染出 Javassist 实际编译的确切代码gate 字段、探针调用点等一应俱全无需依赖反编译。磁盘路径默认取WorkPath.getPath()的父目录下的oal-rt/见 getGeneratedFilePath()每次启动会先清理旧内容prepareRTTempFolder兼容 Docker 卷挂载场景。5.2 SW_DSL_DEBUGGING_INJECTION_ENABLED切换调试模板分支当SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue时代码生成切换到 with-debug 模板dispatcher 为每条指标生成debug_metric的GateHolder字段并在指标处理方法doMetric的各阶段插入OALDebug.captureXxx(...)探针调用点同时这些内容也会出现在转储的.java文件中。从 OALClassGeneratorV2.generateDispatcherClass() 的源码可以看出具体实现细节只有当DSLDebugCodegenSwitch.isInjectionEnabled()为真时dispatcher 才会实现DebugHolderProvider接口、添加debug_oalRuleName的GateHolder字段通过GateHolder.withMetadata(...)工厂方法打上{ruleName, sourceLine}元数据、生成debugHolder(String metricName)查找方法与debugRuleNames()枚举方法探针调用点的生成选择两个模板之一dispatcher/doMetrics.ftl无调试与未启用 dsl-debugging 的构建字节码完全一致或dispatcher/doMetricsWithDebug.ftl带按阶段探针探针调用被isGateOn()守卫调试采用按指标per-metric粒度的 gate每个指标只有自己的GateHolder同一 Source 上的其他指标探针保持关闭与 MAL/LAL 的会话粒度对称。两个变量相互独立SW_DYNAMIC_CLASS_ENGINE_DEBUG只控制是否落盘SW_DSL_DEBUGGING_INJECTION_ENABLED只控制代码生成走哪个模板分支。这套机制非常适合排查代码生成问题或对比 V1 与 V2 的产出差异CLAUDE.md 明确提到This is useful for debugging code generation issues or comparing V1 vs V2 output。5.3 相关测试佐证仓库测试对该调试路径有完整覆盖OALClassGeneratorV2Test生成器行为、OALSourceAttributionTest生成类与 OAL 源位置/行号的关联即 sourceFile/签名行归属、RuntimeOALGenerationTest运行时生成以及 ProductionOALScriptsTest用生产环境真实脚本做回归。六、运行时集成为何用反射加载CLAUDE.md 指出引擎通过OALEngineLoaderService以反射方式加载因为 Maven reactor 中server-core先于oal-rt编译。查看 OALEngineLoaderService.java 的实现private static OALEngine loadOALEngine(OALDefine define) throws ReflectiveOperationException { Class? engineClass Class.forName(org.apache.skywalking.oal.v2.OALEngineV2); Constructor? constructor engineClass.getConstructor(OALDefine.class); return (OALEngine) constructor.newInstance(define); }server-core只依赖OALEngine接口与OALDefine通过Class.forName(org.apache.skywalking.oal.v2.OALEngineV2)在运行时按全限定名实例化 V2 引擎从而避免在编译期引入对oal-rt的依赖解开模块循环。完整的加载流程load() 方法每个OALDefine只激活一次内部用SetOALDefine去重反射创建OALEngineV2实例注入三类依赖StreamAnnotationListener流注解监听、SourceReceiver.getDispatcherDetectorListener()Source 分发器检测、StorageBuilderFactory存储 Builder 工厂调用engine.start(...)解析并生成类再调用engine.notifyAllListeners()把生成的类注册进流处理管线已加载的 OAL 定义集合通过getLoadedDefines()暴露给 DSL 调试 API用于规则选择器枚举已加载的 OAL 包。load(OALDefine)通常由各 receiver-plugin 模块在ModuleProvider.start()中调用从源码搜索可见 agent-analyzer、mesh、browser、jvm、clr、ebpf、envoy、cilium 等多个接收器模块均调用该服务。这也解释了为何引擎生成的类能无缝集成到 SkyWalking 的流处理管线StreamAnnotationListener.notify(metricsClass)让指标类进入流处理 WorkerDispatcherDetectorListener.addIfAsSourceDispatcher(dispatcherClass)让 dispatcher 类成为 Source 的正式分发器。七、总结与使用建议OAL V2 引擎是 SkyWalking OAP 动态指标体系的基石它以不可变模型 三段式流水线Parser → Enricher → Generator实现了 OAL 脚本到流处理字节码的完整编译通过 Javassist 与 FreeMarker 模板在运行时按需生成 Metrics、MetricsBuilder、Dispatcher 三类类并以两个独立的环境变量提供了从磁盘转储到调试探针注入的分级调试能力。对开发者与运维者的实践建议想理解某个指标如何生成从 core.oal 选一条语句沿OALEngineV2.start()→OALScriptParserV2→MetricDefinitionEnricher→OALClassGeneratorV2的顺序阅读即可掌握从文本到字节码的每一步想排查代码生成问题设置SW_DYNAMIC_CLASS_ENGINE_DEBUGtrue重启 OAP检查oal-rt/目录下转储的.class与.java源文件IDE 打开.java即可看到 Javassist 的实际编译输入想启用指标级调试会话配合SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue与 dsl-debugging 模块oap-server/server-admin/dsl-debugging使用可在运行时按 OAL 规则名开启/关闭探针采集想为 OAL 增加新函数或 Source关注MetricsHolder函数类注册与SourceColumnsFactorySource 列元数据并参照 OALParser.g4 语法 扩展语法。相关源码与文档索引引擎文档oap-server/oal-rt/CLAUDE.md、oap-server/oal-rt/V2_IMPLEMENTATION_SUMMARY.md引擎入口OALEngineV2.java解析器OALScriptParserV2.java富化器MetricDefinitionEnricher.java生成器OALClassGeneratorV2.java运行时加载OALEngineLoaderService.java内置脚本oap-server/server-starter/src/main/resources/oal语法定义oal-grammar赞分享可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载相关推荐Apache SkyWalking 8.9.0 版本全解析OAL 引擎强化、IoTDB 存储与可观测性增强Apache SkyWalking 8.9.0 版本全解析OAL 引擎强化、IoTDB 存储与可观测性增强 8.9.0 是 Apache SkyWalking可观测性APM链路追踪指标监控日志分析微服务Apache SkyWalking OAL 完全指南用 Observability Analysis Language 定义流式指标与分析逻辑Apache SkyWalking OAL 完全指南用 Observability Analysis Language 定义流式指标与分析逻辑 导读 Apac可观测性APM链路追踪指标监控日志分析微服务Apache SkyWalking OAL 调试 API 实战指南逐指标捕获 Source 到 Metrics 的每一条流水线样本Apache SkyWalking OAL 调试 API 实战指南逐指标捕获 Source 到 Metrics 的每一条流水线样本 本文对应 SkyWalki可观测性APM链路追踪指标监控日志分析微服务上一篇3分钟解决电视盒子难题TVBoxOSC远程协助功能全攻略下一篇从单点故障到无限扩展Doris高可用与弹性架构设计全景解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入解析 Apache SkyWalking OAL V2 引擎：从 OAL 脚本到流式处理字节码的完整编译管线
可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载导读本文聚焦 Apache SkyWalking 后端OAP Server中负责指标定义与动态编译的核心组件——OALObservability Analysis LanguageV2 引擎源码位于 oap-server/oal-rt。OAL 是 SkyWalking 自研的可观测性分析语言运维人员通过编写.oal脚本即可声明式地定义监控指标如服务响应时间、SLA、CPM、百分位等OAL 引擎则在 OAP 启动时把脚本实时编译为可直接挂入流处理管线的 Java 字节码。读完本文你将掌握 OAL V2 引擎的完整流水线解析 → 元数据富化 → 字节码生成、不可变数据模型与设计原则、两级调试开关的使用方法以及引擎与 server-core 的解耦加载机制并能结合仓库源码与真实 OAL 脚本直接上手排查与二次开发。一、OAL V2 引擎是什么唯一且独立的 OAL 实现在 Apache SkyWalking 中OALObservability Analysis Language用于定义从监控数据源Source如Service、ServiceRelation、Endpoint中聚合出的指标。根据 oap-server/oal-rt/CLAUDE.md 的定位说明oal-rt模块承载的 OAL V2 Engine 是当前仓库中唯一的 OAL 实现This is the only OAL implementation它使用 V2 解析器基于 ANTLR产出不可变模型解析 OAL 脚本使用MetricDefinitionEnricher通过反射为模型补充元数据使用OALClassGeneratorV2基于Javassist FreeMarker 模板在运行时生成 Java 类。引擎入口类为 OALEngineV2.java其类注释明确列出了三项职责与核心收益使用 V2 解析器解析 OAL 脚本不可变模型使用MetricDefinitionEnricher富化 V2 模型元数据使用 V2 模板OALClassGeneratorV2生成类。同时强调其收益清晰的不可变数据模型、类型安全的过滤值与函数参数、带源码位置追踪的更好错误信息、完全独立无 V1 代码依赖。1.1 真实 OAL 脚本长什么样OAP 内置了多份真实 OAL 脚本位于 oap-server/server-starter/src/main/resources/oal 目录下包括core.oal、browser.oal、java-agent.oal、mesh.oal、ebpf.oal、cilium.oal、virtual-gen-ai.oal等。以 core.oal 为例// Service scope metrics service_resp_time from(Service.latency).longAvg().decorator(ServiceDecorator); service_sla from(Service.*).percent(status true).decorator(ServiceDecorator); service_cpm from(Service.*).cpm().decorator(ServiceDecorator); service_percentile from(Service.latency).percentile2(10); // p50, p75, p90, p95, p99 service_apdex from(Service.latency).apdex(name, status).decorator(ServiceDecorator); service_mq_consume_count from(Service.*).filter(type RequestType.MQ).count(); service_mq_consume_latency from((str-long)Service.tag[transmission.latency]) .filter(type RequestType.MQ).filter(tag[transmission.latency] ! null).longAvg(); // Service relation scope metrics for topology service_relation_client_cpm from(ServiceRelation.*).filter(detectPoint DetectPoint.CLIENT).cpm(); service_relation_server_resp_time from(ServiceRelation.latency).filter(detectPoint DetectPoint.SERVER).longAvg();可以看到 OAL 的典型语法结构指标名 from(Source.属性).filter(条件).聚合函数(参数)支持decorator装饰器、filter过滤含枚举比较、Map 取值tag[key]、类型转换(str-long)以及percentile2(10)这类多值聚合函数。这些脚本正是 V2 引擎每次启动时的真实输入。二、包结构四个职责清晰的子包根据 CLAUDE.md 的包结构说明已与源码 oal-rt 主源码目录 逐一核对org.apache.skywalking.oal.v2/ ├── model/ # 不可变数据模型解析器输出 │ ├── SourceLocation # 源文件位置用于错误报告 │ ├── SourceReference # from(Service.latency) │ ├── FunctionCall # longAvg(), percentile2(10) │ ├── FunctionArgument # 类型化函数参数 │ ├── FilterOperator # 枚举: , !, , , like, in │ ├── FilterExpression # latency 100 │ ├── FilterValue # 类型化过滤值 │ └── MetricDefinition # 完整解析后的指标 ├── parser/ # OAL 脚本解析 │ ├── OALListenerV2 # ANTLR 解析树监听器 │ └── OALScriptParserV2 # 解析器门面 ├── generator/ # 代码生成 │ ├── CodeGenModel # 代码生成数据模型 │ ├── MetricDefinitionEnricher # 元数据富化 │ └── OALClassGeneratorV2 # Javassist 字节码生成器 ├── metadata/ # Source/指标元数据工具 │ ├── SourceColumnsFactory │ ├── SourceColumn │ ├── FilterMatchers │ └── MetricsHolder ├── util/ # 代码生成工具 │ ├── ClassMethodUtil │ └── TypeCastUtil └── OALEngineV2 # 主引擎入口每个子包的职责边界非常清晰model纯数据模型只承载一条 OAL 语句解析后是什么不含任何生成逻辑parser把.oal文本变成MetricDefinition列表generator把富化后的CodeGenModel变成可加载的 Java 类metadata负责从 Source 类、Metrics 类上反射抽取列信息、匹配器信息util方法名拼接getter/setter、类型转换等辅助工具。2.1 过滤器运算符全集model包下的 FilterOperator.java 定义了 OAL 支持的全部过滤运算符运算符枚举值匹配器类型适用值类型EQUALequal数值/字符串/布尔/枚举!NOT_EQUALnotEqual数值/字符串/枚举/nullGREATERgreater数值LESSless数值GREATER_EQUALgreaterEqual数值LESS_EQUALlessEqual数值likeLIKElike字符串inINin数组containCONTAINcontain字符串not containNOT_CONTAINnotContain字符串结合 MetricDefinitionEnricher.java 中的mapOperatorToExpressionType方法可以看到完整的映射关系布尔值映射到booleanMatch/booleanNotEqualMatch数值映射到numberMatch/greaterMatch/lessMatch等字符串映射到stringMatch/likeMatch/containMatch数组映射到inMatch枚举比较则复用字符串匹配器如type RequestType.MQ。三、核心流水线Parser → Enricher → GeneratorCLAUDE.md 给出了整个引擎的三段式流水线┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ .oal file │───▶│ Parser │───▶│ Enricher │───▶│ Generator │ │ │ │ │ │ │ │ │ │ OAL script │ │ MetricDef │ │ CodeGenModel│ │ Bytecode/ │ │ │ │ (immutable) │ │ (metadata) │ │ Source │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ParserOALScriptParserV2把.oal文件解析为不可变的MetricDefinition对象EnricherMetricDefinitionEnricher通过反射补充元数据Source 列、持久化字段GeneratorOALClassGeneratorV2使用 Javassist 和 FreeMarker 模板生成 Java 类。3.1 入口调用链OALEngineV2.start()OALEngineV2.start() 完整实现了上述流水线try (Reader reader ResourceUtils.read(oalDefine.getConfigFile())) { // 1. 解析 OALScriptParserV2 v2Parser OALScriptParserV2.parse(reader, oalDefine.getConfigFile()); // 2. 富化 ListCodeGenModel codeGenModels enrichMetrics(v2Parser.getMetrics()); // 3. 生成 classGeneratorV2.generateClassAtRuntime( codeGenModels, v2Parser.getDisabledSources(), metricsClasses, dispatcherClasses); }启动日志会依次输出解析成功了多少条指标、富化了多少条、最终生成了多少 metrics 类与 dispatcher 类V2 Parser: Successfully parsed N metrics V2 Enricher: Enriched N metrics with metadata OAL Engine V2 started successfully. Generated X metrics classes, Y dispatcher classes3.2 阶段一Parser —— ANTLR 解析树到不可变模型OALScriptParserV2.java 展示了解析流程用OALLexer由 oal-grammar 模块的 ANTLR 语法 生成做词法分析用OALParser做语法分析挂载自定义的OALErrorListener收集带文件名与位置的详细错误信息若有语法错误直接抛出IllegalArgumentException错误信息含源码位置用ParseTreeWalker驱动OALListenerV2遍历解析树产出MetricDefinition列表与disabledSources列表。OALListenerV2在遍历聚合语句exitAggregationStatement时会通过 ANTLR 的Interval 切片把每条指标语句的原文、from(...)片段、聚合函数片段、过滤片段逐字byte-for-byte记录下来供 dsl-debugging 使用详见下文调试输出部分。解析器同时支持直接从字符串解析parse(String script)这在单元测试中非常有用——OALScriptParserV2Test 与 RealOALScriptsTest 就分别覆盖了语法单元测试与真实脚本解析测试。3.3 阶段二Enricher —— 反射注入元数据MetricDefinitionEnricher.enrich() 的八步处理通过MetricsHolder.find(聚合函数名)查找到对应的指标函数类如LongAvgMetrics通过SourceColumnsFactory.getColumns(Source名)获取 Source 类的列元数据字段名、列名、类型、是否 ID、是否分片键等通过DefaultScopeDefine.valueOf(Source名)得到 Source 的 scopeId查找Entrance注解标注的入口方法沿类继承链向上搜索遍历入口方法参数按SourceFrom、ConstOne、Expression、Arg、DefaultValue注解生成对应的参数表达式与参数类型LITERAL_TYPE1、ATTRIBUTE_EXP_TYPE2、EXPRESSION_TYPE3从 Metrics 类收集Column注解的持久化字段按类型生成序列化字段分组int/double/String/long/复杂对象把过滤表达式转换为模板格式含匹配器类名、左右操作数表达式、原文切片。这一步是模型与生成之间的桥梁产出的 CodeGenModel 成为 FreeMarker 模板的数据输入。3.4 阶段三Generator —— Javassist 运行时生成三类类OALClassGeneratorV2.generateClassAtRuntime() 每个指标生成三类类Metrics 类如ServiceRespTimeMetrics继承自父指标类如LongAvgMetrics动态添加 Source 字段带Column、BanyanDB.SeriesID、ElasticSearch.EnableDocValues等注解、无参构造器并从模板生成id、hashCode、remoteHashCode、equals、serialize、deserialize、getMeta、toHour、toDay、appendDebugFields等方法最后打上Stream注解含表名、scopeId、builder 类、processor 类Metrics Builder 类如ServiceRespTimeMetricsBuilder实现存储层 Builder 接口从存储模块指定的模板路径生成entity2Storage、storage2Entity两个方法因此不同存储ES/BanyanDB可提供不同的 builder 模板Dispatcher 类如ServiceDispatcher按 Source 分组一个 Source 对应一个 dispatcher实现SourceDispatcherSource接口为每个指标生成doMetric()方法外加统一的dispatch()分发方法。模板方面V2 引擎使用独立的模板目录/code-templates-v2见 OALClassGeneratorV2 构造器与 V1 模板完全隔离。生成完成后引擎把 metrics 类与 dispatcher 类分别通知给StreamAnnotationListener注册为流处理器和DispatcherDetectorListener注册为 Source 分发器从而接入 SkyWalking 的流处理管线见 OALEngineV2.notifyAllListeners()。四、设计原则为何 V2 采用不可变模型CLAUDE.md 明确列出了 V2 引擎的五条设计原则这些原则在源码中均有落实不可变模型Immutable Models所有解析器输出类不可变且线程安全。以 MetricDefinition.java 为例类被声明为public final class所有字段private final列表字段在构造时通过Collections.unmodifiableList(new ArrayList(...))防御性拷贝实例只能通过Builder构建。类型安全Type Safety用枚举与类型化值替代裸字符串。过滤值由 FilterValue 统一封装区分数值/字符串/布尔/null/枚举/数组运算符是FilterOperator枚举而非字符串。Builder 模式Builder Pattern复杂对象全部使用流式 Builder。MetricDefinition、SourceReference、FilterExpression、FunctionCall均内置Builder内部类。关注点分离Separation of Concerns解析模型 ≠ 代码生成模型。MetricDefinition解析输出与CodeGenModel生成输入是两个独立类中间由 Enricher 转换。可测试性Testability模型可以不经过解析直接手工构造便于单元测试。例如 FilterExpressionTest、FunctionCallTest 都是直接构造模型实例进行断言。4.1 关键类一MetricDefinition解析输出CLAUDE.md 给出了一个可以直接运行的构造示例对应 OALservice_resp_time from(Service.latency).filter(latency 0).longAvg()MetricDefinition metric MetricDefinition.builder() .name(service_resp_time) .source(SourceReference.of(Service, latency)) .addFilter(FilterExpression.of(latency, , 0L)) .aggregationFunction(FunctionCall.of(longAvg)) .build();MetricDefinition携带的字段包括name指标名、tableName存储表名缺省等于 name、sourceSource 引用、filters过滤表达式列表、aggregationFunction聚合函数、decorator装饰器、location源码位置、sourceText整条语句原文与fromTextfrom(...)片段原文。其中后两者是 ANTLR Interval 切片的结果专门服务于 dsl-debugging 的逐字匹配。SourceReference见 SourceReference.java支持三种形态from(Service.latency) // nameService, attributelatency from(Service.*) // nameService, 通配 from((long)Service.tag[key]) // nameService, attributetag[key], castTypelong4.2 关键类二CodeGenModel生成输入CodeGenModel是 Enricher 的产物供模板与 Javassist 消费。CLAUDE.md 给出了其核心访问方式// Created by MetricDefinitionEnricher CodeGenModel model enricher.enrich(metricDefinition); // Contains: source columns, persistent fields, metrics class info, etc. model.getFieldsFromSource(); // 从 Source 拷贝的字段 model.getPersistentFields(); // 用于存储的字段 model.getMetricsClassName(); // 例如 LongAvgMetrics从 MetricDefinitionEnricher.enrich() 可以看到完整的 CodeGenModel 组成varName、metricsNamesnake_case 转 PascalCase、tableName、sourceName、sourceScopeId、from含 fromText、functionName、aggregationSourceText、sourceLine、metricSourceText、metricsClassName、filters、fieldsFromSource、persistentFields、serializeFields、entranceMethod、sourceDecorator。所有与 dsl-debugging 相关的原文切片字段fromText、aggregationSourceText、metricSourceText都由解析器在 ANTLR Interval 切片阶段捕获代码生成阶段不需要做任何运行时重建。五、调试输出两个独立的环境变量开关CLAUDE.md 着重介绍了 OAL 引擎的调试机制——通过两个相互独立的环境变量控制环境变量作用SW_DYNAMIC_CLASS_ENGINE_DEBUGtrue控制磁盘转储把生成的.class文件写入磁盘SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue控制代码生成分支切换为带调试探针的模板5.1 SW_DYNAMIC_CLASS_ENGINE_DEBUG转储 class 与配套 java 源文件在 OALClassGeneratorV2 构造器 中openEngineDebug StringUtil.isNotEmpty(System.getenv(SW_DYNAMIC_CLASS_ENGINE_DEBUG))读取该变量。开启后生成的.class会写入磁盘且每个.class都会配对一个ClassName.java生成源码文件——即 Javassist 编译时输入的确切 Java 源码synthetic{skywalking}/oal-rt/ ├── metrics/ │ ├── ServiceRespTimeMetrics.class │ └── ServiceRespTimeMetrics.java ← Javassist compile input (synthetic) └── dispatcher/ ├── ServiceRelationDispatcher.class └── ServiceRelationDispatcher.java配套.java文件存在的意义非常实际Javassist 产出的字节码经常让反编译器如 FernFlower困惑——没有goto合并、混合类型的槽位复用、调试注入的if (gate.isGateOn()) { ... }链FernFlower 常常直接退化为 compiled code 存根。而.java源文件可以让 IDE 的 source-attach 直接渲染出 Javassist 实际编译的确切代码gate 字段、探针调用点等一应俱全无需依赖反编译。磁盘路径默认取WorkPath.getPath()的父目录下的oal-rt/见 getGeneratedFilePath()每次启动会先清理旧内容prepareRTTempFolder兼容 Docker 卷挂载场景。5.2 SW_DSL_DEBUGGING_INJECTION_ENABLED切换调试模板分支当SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue时代码生成切换到 with-debug 模板dispatcher 为每条指标生成debug_metric的GateHolder字段并在指标处理方法doMetric的各阶段插入OALDebug.captureXxx(...)探针调用点同时这些内容也会出现在转储的.java文件中。从 OALClassGeneratorV2.generateDispatcherClass() 的源码可以看出具体实现细节只有当DSLDebugCodegenSwitch.isInjectionEnabled()为真时dispatcher 才会实现DebugHolderProvider接口、添加debug_oalRuleName的GateHolder字段通过GateHolder.withMetadata(...)工厂方法打上{ruleName, sourceLine}元数据、生成debugHolder(String metricName)查找方法与debugRuleNames()枚举方法探针调用点的生成选择两个模板之一dispatcher/doMetrics.ftl无调试与未启用 dsl-debugging 的构建字节码完全一致或dispatcher/doMetricsWithDebug.ftl带按阶段探针探针调用被isGateOn()守卫调试采用按指标per-metric粒度的 gate每个指标只有自己的GateHolder同一 Source 上的其他指标探针保持关闭与 MAL/LAL 的会话粒度对称。两个变量相互独立SW_DYNAMIC_CLASS_ENGINE_DEBUG只控制是否落盘SW_DSL_DEBUGGING_INJECTION_ENABLED只控制代码生成走哪个模板分支。这套机制非常适合排查代码生成问题或对比 V1 与 V2 的产出差异CLAUDE.md 明确提到This is useful for debugging code generation issues or comparing V1 vs V2 output。5.3 相关测试佐证仓库测试对该调试路径有完整覆盖OALClassGeneratorV2Test生成器行为、OALSourceAttributionTest生成类与 OAL 源位置/行号的关联即 sourceFile/签名行归属、RuntimeOALGenerationTest运行时生成以及 ProductionOALScriptsTest用生产环境真实脚本做回归。六、运行时集成为何用反射加载CLAUDE.md 指出引擎通过OALEngineLoaderService以反射方式加载因为 Maven reactor 中server-core先于oal-rt编译。查看 OALEngineLoaderService.java 的实现private static OALEngine loadOALEngine(OALDefine define) throws ReflectiveOperationException { Class? engineClass Class.forName(org.apache.skywalking.oal.v2.OALEngineV2); Constructor? constructor engineClass.getConstructor(OALDefine.class); return (OALEngine) constructor.newInstance(define); }server-core只依赖OALEngine接口与OALDefine通过Class.forName(org.apache.skywalking.oal.v2.OALEngineV2)在运行时按全限定名实例化 V2 引擎从而避免在编译期引入对oal-rt的依赖解开模块循环。完整的加载流程load() 方法每个OALDefine只激活一次内部用SetOALDefine去重反射创建OALEngineV2实例注入三类依赖StreamAnnotationListener流注解监听、SourceReceiver.getDispatcherDetectorListener()Source 分发器检测、StorageBuilderFactory存储 Builder 工厂调用engine.start(...)解析并生成类再调用engine.notifyAllListeners()把生成的类注册进流处理管线已加载的 OAL 定义集合通过getLoadedDefines()暴露给 DSL 调试 API用于规则选择器枚举已加载的 OAL 包。load(OALDefine)通常由各 receiver-plugin 模块在ModuleProvider.start()中调用从源码搜索可见 agent-analyzer、mesh、browser、jvm、clr、ebpf、envoy、cilium 等多个接收器模块均调用该服务。这也解释了为何引擎生成的类能无缝集成到 SkyWalking 的流处理管线StreamAnnotationListener.notify(metricsClass)让指标类进入流处理 WorkerDispatcherDetectorListener.addIfAsSourceDispatcher(dispatcherClass)让 dispatcher 类成为 Source 的正式分发器。七、总结与使用建议OAL V2 引擎是 SkyWalking OAP 动态指标体系的基石它以不可变模型 三段式流水线Parser → Enricher → Generator实现了 OAL 脚本到流处理字节码的完整编译通过 Javassist 与 FreeMarker 模板在运行时按需生成 Metrics、MetricsBuilder、Dispatcher 三类类并以两个独立的环境变量提供了从磁盘转储到调试探针注入的分级调试能力。对开发者与运维者的实践建议想理解某个指标如何生成从 core.oal 选一条语句沿OALEngineV2.start()→OALScriptParserV2→MetricDefinitionEnricher→OALClassGeneratorV2的顺序阅读即可掌握从文本到字节码的每一步想排查代码生成问题设置SW_DYNAMIC_CLASS_ENGINE_DEBUGtrue重启 OAP检查oal-rt/目录下转储的.class与.java源文件IDE 打开.java即可看到 Javassist 的实际编译输入想启用指标级调试会话配合SW_DSL_DEBUGGING_INJECTION_ENABLEDtrue与 dsl-debugging 模块oap-server/server-admin/dsl-debugging使用可在运行时按 OAL 规则名开启/关闭探针采集想为 OAL 增加新函数或 Source关注MetricsHolder函数类注册与SourceColumnsFactorySource 列元数据并参照 OALParser.g4 语法 扩展语法。相关源码与文档索引引擎文档oap-server/oal-rt/CLAUDE.md、oap-server/oal-rt/V2_IMPLEMENTATION_SUMMARY.md引擎入口OALEngineV2.java解析器OALScriptParserV2.java富化器MetricDefinitionEnricher.java生成器OALClassGeneratorV2.java运行时加载OALEngineLoaderService.java内置脚本oap-server/server-starter/src/main/resources/oal语法定义oal-grammar赞分享可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载相关推荐Apache SkyWalking 8.9.0 版本全解析OAL 引擎强化、IoTDB 存储与可观测性增强Apache SkyWalking 8.9.0 版本全解析OAL 引擎强化、IoTDB 存储与可观测性增强 8.9.0 是 Apache SkyWalking可观测性APM链路追踪指标监控日志分析微服务Apache SkyWalking OAL 完全指南用 Observability Analysis Language 定义流式指标与分析逻辑Apache SkyWalking OAL 完全指南用 Observability Analysis Language 定义流式指标与分析逻辑 导读 Apac可观测性APM链路追踪指标监控日志分析微服务Apache SkyWalking OAL 调试 API 实战指南逐指标捕获 Source 到 Metrics 的每一条流水线样本Apache SkyWalking OAL 调试 API 实战指南逐指标捕获 Source 到 Metrics 的每一条流水线样本 本文对应 SkyWalki可观测性APM链路追踪指标监控日志分析微服务上一篇3分钟解决电视盒子难题TVBoxOSC远程协助功能全攻略下一篇从单点故障到无限扩展Doris高可用与弹性架构设计全景解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考