You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wa...@apache.org on 2026/10/12 01:16:37 UTC
(skywalking) 01/01: Add the Trace Analysis Language to analyze OTLP traces into metrics and topology
This is an automated email from the ASF dual-hosted git repository.
wankai123 pushed a commit to branch feature/otlp-trace-analysis-language
in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 8ccdc0bc490b356a172223da1b04de2b962a019f
Author: wankai123 <wa...@foxmail.com>
AuthorDate: Mon Oct 12 09:16:25 2026 +0800
Add the Trace Analysis Language to analyze OTLP traces into metrics and topology
TAL is a compiled DSL in the new trace-analyzer module. It analyzes the spans the OTel receiver accepts, in both OTLP trace storage modes, and emits metrics, topology and records through the meter system. The shipped tal/otlp-default.yaml registers OTLP services under the OTLP_SERVICE layer and the peers they call under OTLP_VIRTUAL_DATABASE, OTLP_VIRTUAL_CACHE and OTLP_VIRTUAL_MQ, folding address-named peers onto services through network address aliases and client/server span pairing.
---
apm-dist/src/main/assembly/binary.xml | 1 +
docs/en/changes/changes.md | 1 +
docs/en/concepts-and-designs/tal.md | 257 ++++
docs/en/setup/backend/configuration-vocabulary.md | 5 +
docs/en/setup/backend/otlp-trace.md | 7 +
docs/en/setup/backend/trace-analyzer.md | 158 ++
docs/en/swip/SWIP-otlp-trace-analysis-language.md | 1518 +++++++++++++++++++
docs/en/swip/SWIP-otlp-trace-metrics.md | 747 ++++++++++
docs/menu.yml | 4 +
.../listener/DatabaseSlowStatementBuilder.java | 57 +-
...walking.oap.server.core.source.TALOutputBuilder | 19 +
.../skywalking/oap/meter/analyzer/v2/Analyzer.java | 172 +--
oap-server/analyzer/pom.xml | 1 +
.../trace-analyzer}/pom.xml | 47 +-
.../apache/skywalking/tal/rt/grammar/TALLexer.g4 | 174 +++
.../apache/skywalking/tal/rt/grammar/TALParser.g4 | 424 ++++++
.../oap/trace/analyzer/v2/compiler/ExprType.java | 51 +
.../analyzer/v2/compiler/TALBlockCodegen.java | 717 +++++++++
.../analyzer/v2/compiler/TALClassGenerator.java | 290 ++++
.../analyzer/v2/compiler/TALCodegenHelper.java | 62 +
.../trace/analyzer/v2/compiler/TALDefCodegen.java | 462 ++++++
.../oap/trace/analyzer/v2/compiler/TALGenCtx.java | 155 ++
.../trace/analyzer/v2/compiler/TALLocalVar.java} | 30 +-
.../analyzer/v2/compiler/TALMetricDeclaration.java | 69 +
.../analyzer/v2/compiler/TALMetricFunction.java | 101 ++
.../analyzer/v2/compiler/TALPrivateMethod.java} | 28 +-
.../analyzer/v2/compiler/TALRootResolver.java | 98 ++
.../trace/analyzer/v2/compiler/TALScriptModel.java | 665 +++++++++
.../analyzer/v2/compiler/TALScriptParser.java | 900 ++++++++++++
.../analyzer/v2/compiler/TALSpanRootResolver.java | 234 +++
.../analyzer/v2/compiler/TALValueCodegen.java | 1543 ++++++++++++++++++++
.../analyzer/v2/compiler/model/BinaryOp.java} | 33 +-
.../analyzer/v2/compiler/model/CompareOp.java} | 23 +-
.../analyzer/v2/compiler/model/LogicalOp.java} | 23 +-
.../v2/compiler/model/TALBoolConditionValue.java} | 23 +-
.../v2/compiler/model/TALComparisonCondition.java} | 26 +-
.../analyzer/v2/compiler/model/TALCondition.java} | 22 +-
.../v2/compiler/model/TALConditionValue.java} | 22 +-
.../v2/compiler/model/TALDefStatement.java} | 24 +-
.../v2/compiler/model/TALExprCondition.java} | 23 +-
.../v2/compiler/model/TALFieldSegment.java} | 22 +-
.../v2/compiler/model/TALFunctionArg.java} | 22 +-
.../model/TALFunctionCallConditionValue.java} | 23 +-
.../v2/compiler/model/TALIndexSegment.java} | 23 +-
.../v2/compiler/model/TALLogicalCondition.java} | 23 +-
.../v2/compiler/model/TALMethodSegment.java} | 22 +-
.../v2/compiler/model/TALNotCondition.java} | 23 +-
.../v2/compiler/model/TALNullConditionValue.java} | 22 +-
.../compiler/model/TALNumberConditionValue.java} | 23 +-
.../compiler/model/TALStringConditionValue.java} | 23 +-
.../analyzer/v2/compiler/model/TALValueAccess.java | 85 ++
.../model/TALValueAccessConditionValue.java} | 23 +-
.../v2/compiler/model/TALValueAccessSegment.java} | 22 +-
.../compiler/rt/TalExpressionPackageHolder.java} | 23 +-
.../analyzer/v2/compiler/rt/TalRuntimeHelper.java | 746 ++++++++++
.../trace/analyzer/v2/dsl/ExecutionContext.java | 236 +++
.../oap/trace/analyzer/v2/dsl/TalDSL.java | 136 ++
.../oap/trace/analyzer/v2/dsl/TalExpression.java | 44 +
.../oap/trace/analyzer/v2/dsl/spec/FilterSpec.java | 197 +++
.../analyzer/v2/dsl/spec/RateLimitingSampler.java | 49 +
.../analyzer/v2/module/TraceAnalyzerModule.java | 48 +
.../oap/trace/analyzer/v2/provider/TALConfig.java | 87 ++
.../oap/trace/analyzer/v2/provider/TALConfigs.java | 220 +++
.../v2/provider/TraceAnalyzerModuleConfig.java | 75 +
.../v2/provider/TraceAnalyzerModuleProvider.java | 146 ++
.../analyzer/v2/provider/span/AliasRegistrar.java | 118 ++
.../v2/provider/span/ITraceAnalyzerService.java | 46 +
.../analyzer/v2/provider/span/KnownServices.java | 58 +
.../analyzer/v2/provider/span/PairingFact.java | 127 ++
.../analyzer/v2/provider/span/PairingWorker.java | 42 +
.../trace/analyzer/v2/provider/span/SeenSpans.java | 62 +
.../analyzer/v2/provider/span/SpanPairing.java | 171 +++
.../v2/provider/span/TraceAnalyzerServiceImpl.java | 223 +++
.../provider/span/listener/SpanFilterListener.java | 356 +++++
.../analyzer/v2/spi/OtlpTALSourceTypeProvider.java | 84 ++
.../analyzer/v2/spi/TALSourceTypeProvider.java | 83 ++
...ywalking.oap.server.library.module.ModuleDefine | 19 +
...alking.oap.server.library.module.ModuleProvider | 19 +
...oap.trace.analyzer.v2.spi.TALSourceTypeProvider | 19 +
.../oap/trace/analyzer/v2/ShippedRules.java | 96 ++
.../v2/compiler/AttributionSlowStatement.java | 55 +
.../v2/compiler/DumpShippedRuleSourcesTest.java | 115 ++
.../v2/compiler/TALClassGeneratorTest.java | 226 +++
.../analyzer/v2/compiler/TALScriptParserTest.java | 306 ++++
.../v2/compiler/TALShippedRuleCompileTest.java | 137 ++
.../v2/compiler/TALSourceAttributionTest.java | 125 ++
.../v2/compiler/TestSlowStatementBuilder.java | 55 +
.../trace/analyzer/v2/dsl/TALExecutionTest.java | 653 +++++++++
.../analyzer/v2/dsl/TALWorkedExampleTest.java | 585 ++++++++
.../oap/trace/analyzer/v2/dsl/TestSpanInput.java} | 34 +-
.../v2/dsl/TestSpanSourceTypeProvider.java} | 35 +-
.../analyzer/v2/provider/ShippedSlowStatement.java | 55 +
.../analyzer/v2/provider/ShippedTalFileTest.java | 128 ++
.../analyzer/v2/provider/span/SeenSpansTest.java | 54 +
.../analyzer/v2/provider/span/SpanPairingTest.java | 186 +++
.../span/TraceAnalyzerServiceImplTest.java | 260 ++++
.../listener/SpanFilterListenerFactoryTest.java | 50 +
.../oap/server/core/CoreModuleProvider.java | 3 +
.../skywalking/oap/server/core/analysis/Layer.java | 20 +
.../analysis/meter/EntityTrafficGenerator.java | 234 +++
.../server/core/analysis/meter/MeterEntity.java | 84 +-
.../meter/function/ApdexArgument.java} | 28 +-
.../meter/function/apdex/ApdexFunction.java | 307 ++++
.../meter/function/percent/PercentFunction.java | 283 ++++
.../config/ComponentLibraryCatalogService.java | 21 +
.../config/IComponentLibraryCatalogService.java | 7 +
.../oap/server/core/source/TALOutputBuilder.java | 73 +
.../oap/server/core/trace/SpanAnalysisResult.java | 58 +
.../oap/server/core/trace/SpanMetadata.java | 155 ++
.../otel-receiver-plugin/pom.xml | 6 +
.../receiver/otel/OtelMetricReceiverProvider.java | 9 +
.../server/receiver/otel/otlp/OTLPSpanForward.java | 11 +-
.../otel/otlp/OpenTelemetryTraceHandler.java | 180 ++-
.../otel/OtelMetricReceiverProviderTest.java | 22 +
.../receiver/otel/otlp/OTLPSpanForwardTest.java | 8 +-
.../otlp/ShippedRuleOverRecordedTraceTest.java | 434 ++++++
.../resources/tal/otlp-trace-get-api-cart.json | 1030 +++++++++++++
oap-server/server-starter/pom.xml | 1 +
.../src/main/resources/application.yml | 24 +
.../src/main/resources/component-libraries.yml | 5 +
.../src/main/resources/tal/otlp-default.yaml | 265 ++++
.../mock/MockComponentLibraryCatalogService.java | 5 +
.../cases/otlp-traces/native/banyandb/e2e.yaml | 1 +
test/e2e-v2/cases/otlp-traces/native/es/e2e.yaml | 1 +
.../tal-endpoints-productcatalogservice.yml | 19 +
.../native/expected/tal-metric-sla-10000.yml | 31 +
.../native/expected/tal-metric-values.yml | 30 +
.../otlp-traces/native/expected/tal-services.yml | 31 +
.../otlp-traces/native/expected/tal-topology.yml | 56 +
.../e2e-v2/cases/otlp-traces/native/mysql/e2e.yaml | 1 +
.../e2e-v2/cases/otlp-traces/native/tal-cases.yaml | 37 +
test/e2e-v2/cases/storage/expected/config-dump.yml | 6 +
132 files changed, 18994 insertions(+), 653 deletions(-)
diff --git a/apm-dist/src/main/assembly/binary.xml b/apm-dist/src/main/assembly/binary.xml
index cf6bea9890..6988daad57 100644
--- a/apm-dist/src/main/assembly/binary.xml
+++ b/apm-dist/src/main/assembly/binary.xml
@@ -70,6 +70,7 @@
<include>openapi-definitions/*/*.yaml</include>
<include>otel-rules/**</include>
<include>lal/*</include>
+ <include>tal/*</include>
<include>log-mal-rules/**</include>
<include>telegraf-rules/*</include>
<include>cilium-rules/*</include>
diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md
index e6d421ba59..634d8b6108 100644
--- a/docs/en/changes/changes.md
+++ b/docs/en/changes/changes.md
@@ -35,6 +35,7 @@
* Fix the Elasticsearch `BulkProcessor` treating a bulk write as fully successful whenever the overall HTTP status was 200, even when Elasticsearch rejected individual items in the same response, for example a 429 `cluster_block_exception` when an index is switched to `read_only_allow_delete` by the flood-stage disk watermark. The response body's `errors` flag and per-item `status`/`error` are now decoded and checked on every 200 response; a rejected request's future now completes except [...]
* AI agent conversations adopt AI Sessionizer `6691c36`, and withhold what the runtime sent the model. The Sessionizer names the records that carry the system prompt and the tool schemas with the flags `system_prompt` and `tool_schemas`; the `hide` setting (`SW_AI_AGENT_CONVERSATION_HIDE`) names what this OAP withholds from every reader; the routes take no parameter for it. Withholding happens as a conversation is served, and only then: the storage holds every file whole, and both routes [...]
* Fix endpoints registered from logs missing from `findEndpoint` (the endpoint list) when it is queried with a time range. The query filters on an endpoint's `last_ping`, which endpoints registered from logs, from virtual MQ spans, from cross-thread segment references and from Cilium Hubble never set, so they kept `last_ping` at `0`, and an endpoint also seen in traces was reset to `0` whenever one of those sources wrote it last. Every endpoint source now sets `last_ping`, and an update [...]
+* Add the Trace Analysis Language (TAL), a compiled DSL in the new `trace-analyzer` module that turns the spans arriving over OTLP into metrics, topology and records through the meter system, in both OTLP trace storage modes and ahead of the receiver's head sampling. The shipped `tal/otlp-default.yaml` reads the OpenTelemetry semantic conventions, current spellings first and the deprecated ones as fallbacks, and registers OTLP services under the new `OTLP_SERVICE` layer with `otlp_servic [...]
#### UI
* Add a Virtual GenAI evaluation-record page and evaluation-score chart in Horizon UI, so operators can inspect evaluation result, level, reason, judge model, timestamp, trace linkage, and the `gen_ai_model_evaluation_score_ppm` trend for evaluated records.
diff --git a/docs/en/concepts-and-designs/tal.md b/docs/en/concepts-and-designs/tal.md
new file mode 100644
index 0000000000..788b1b6802
--- /dev/null
+++ b/docs/en/concepts-and-designs/tal.md
@@ -0,0 +1,257 @@
+# Trace Analysis Language
+
+Trace Analysis Language (TAL) in SkyWalking is a Domain-Specific Language (DSL) to analyze the spans that arrive over
+the OpenTelemetry protocol. A TAL rule reads one span at a time and decides what it is, which service, instance and
+endpoint it belongs to, which metrics it feeds, which record it writes, and whether the span itself is stored. The
+metrics go through the meter system, so they are stored, downsampled, queried and alerted on like every meter
+metric.
+
+The TAL config files are in YAML format, and are located under directory `tal`. You can set
+`trace-analyzer/default/talFiles` in the `application.yml` file or set environment variable `SW_TRACE_TAL_FILES` to
+activate specific TAL config files. The files are read when the OAP starts. See
+[OpenTelemetry Trace Analysis](../setup/backend/trace-analyzer.md) for the module's settings and for what the shipped
+rule file produces.
+
+Anyone who has written a [LAL](lal.md) rule can read a TAL rule: the grammar is LAL's, with the log-specific parts
+removed and span-specific parts added. The differences are listed at the end of this page.
+
+## Rule file
+
+```yaml
+# tal/<file>.yaml
+metricPrefix: otlp # every metric declared in this file is stored as <metricPrefix>_<name>
+layerDefinitions: # optional, the same contract as LAL and MAL: registered before the rules compile
+ - name: IOT_FLEET
+ ordinal: 1000
+ normal: true
+rules:
+ - name: otlp-service # unique within its layer
+ layer: auto # a registered layer name, or `auto`
+ inputType: otlp # optional; the only input this release ships, and the default
+ outputType: SlowSQL # optional; the record the rule writes, see Output Type
+ dsl: |
+ filter { ... }
+```
+
+A rule names exactly one `inputType`. The OAP refuses to start on a rule whose `layer` is not registered, naming the
+rule and the layer; declare the layer under `layerDefinitions` or use a built-in one.
+
+## Span metadata
+
+Every rule reads the span through two roots. `meta` holds what the receiver derived from the span and its resource,
+and it means the same thing whatever the input:
+
+| `meta` field | Source on an OTLP span |
+|---|---|
+| `service` | the resource's `service.name`; the receiver's fallbacks are described in [OpenTelemetry Trace Format](../setup/backend/otlp-trace.md#service-name) |
+| `serviceInstance` | the resource's `service.instance.id` |
+| `endpoint` | the span's name, until a rule sets it |
+| `layer` | the resource's `service.layer`, empty when absent; see [Layer](#layer) |
+| `kind` | `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER`, `INTERNAL` or `UNSPECIFIED` |
+| `statusCode`, `statusMessage` | `UNSET`, `OK` or `ERROR`, and the status message |
+| `startTime`, `timestamp` | the span's start and end, in milliseconds; `timestamp` is the minute bucket the metrics land in |
+| `latency` | end minus start, in milliseconds |
+| `traceId`, `spanId`, `parentSpanId` | the ids in lowercase hex; `parentSpanId` is empty on a root span |
+| `root` | whether `parentSpanId` is empty |
+| `scopeName`, `scopeVersion` | the instrumentation scope |
+
+`span` is the wire object itself, `io.opentelemetry.proto.trace.v1.Span`, resolved at compile time: `span.name`,
+`span.traceState`, `span.status.message`, `span.eventsCount`. Prefer `meta.kind` and `meta.statusCode` over the
+proto enums in conditions.
+
+## Layer
+
+A span whose resource carries `service.layer` is evaluated by the rules declared for that layer, and by nothing
+else. A span whose resource carries a layer name that is not registered is logged and not analyzed. A span without
+`service.layer` is evaluated by the `layer: auto` rules; an auto rule that does not `abort {}` has claimed the span
+and must set `layer` in its extractor. There is no fallback to `GENERAL`, which is the agent layer: the shipped rule
+puts OpenTelemetry services under `OTLP_SERVICE` and their conjectured peers under `OTLP_VIRTUAL_DATABASE`,
+`OTLP_VIRTUAL_CACHE` and `OTLP_VIRTUAL_MQ`, see [the setup doc](../setup/backend/trace-analyzer.md#layers).
+
+Rules for one layer run in file order, each with its own copy of `meta`, so a rule that overwrites `service` for its
+record does not change what the next rule reads. Each rule decides independently.
+
+## Filter
+
+```text
+filter {
+ <if / def / abort>*
+ extractor { ... }
+ sink { ... } // the record declared by outputType
+ persist { ... } // the span itself
+}
+```
+
+### Global functions
+
+Attributes are reached through functions, all null-safe and returning `""` when absent:
+
+| Function | Returns |
+|---|---|
+| `attr(key, ...)` | the first present span attribute among the keys, rendered as a string: scalars as text, arrays joined by `,`, key-value lists as JSON, bytes as base64. Several keys let one rule serve SDKs on different semantic-convention versions: `attr("db.system.name", "db.system")` |
+| `hasAttr(key, ...)` | whether any of the keys is present on the span |
+| `resource(key, ...)` | the same over the resource attributes: `resource("telemetry.sdk.language")` |
+| `scopeAttr(key, ...)` | the same over the instrumentation scope's attributes |
+| `event(name)` | the first span event with that name, or `null`: `event("exception")?.timeUnixNano` |
+| `eventAttr(name, key, ...)` | an attribute of that event: `eventAttr("exception", "exception.type")` |
+| `component(name)` | the component id from `component-libraries.yml`, matched exactly and then ignoring case, so `attr("rpc.system.name", "rpc.system")` giving `grpc` finds `GRPC` and `postgresql` finds `PostgreSQL`; `0`, the `Unknown` component, when nothing matches |
+| `resolveAlias(address)` | the service an address names, see [Address-named peers](#address-named-peers); the address unchanged when none is known yet |
+| `urlHost(url)` | the authority of a URL, `host` or `host:port`, without scheme, user info, path, query or fragment; empty when the value has none. For a client that names its target only as `url.full` or `http.url` |
+| `toJson(expr)`, `toJsonArray(expr)` | as in LAL |
+
+A span's attributes are indexed once per span, however many rules and lookups read them.
+
+### Extractor
+
+```text
+extractor {
+ def <name> = <expr> [as <Type>] // any value, including an entity from the metrics block
+ service | instance | endpoint | layer <expr> // overwrite meta.*; also the record's standard fields
+ <field> <expr> [as <Type>] // an output field of the outputType, see Output Type
+ tag '<key>': <expr> // appended to the stored span as a string attribute
+ alias <expr> // the address this span was dialed at, see Address-named peers
+ metrics { ... } // see below
+ if (...) { ... } else if (...) { ... } else { ... }
+ abort {} // stop this rule for this span; it writes nothing and votes nothing
+}
+```
+
+`abort {}` is allowed anywhere: at filter level and inside `extractor`, `sink` and `persist`. In a `layer: auto`
+rule it means "not mine".
+
+### `metrics`
+
+A `metrics {}` block declares one metric and emits one value for this span. The name, the function and the entity
+constructor are literals, so every metric a file declares is known when it compiles and its storage is created
+then.
+
+```text
+metrics {
+ name "<metric>" // literal; stored as <metricPrefix>_<metric>
+ scope <entity> // an entity constructor, or a `def` holding one
+ function <function> // literal, see the table
+ value <expr> // the observation; a number, or a string that parses as one. Not used by percent
+ [match <condition>] // percent only, required: the span counts as a match when true
+ [status <condition>] // apdex only, required: the span counts as successful when true
+ [labels k: v, ...] // required by the *Labeled functions, forbidden otherwise
+ [buckets [n, n, ...]] // required by histogram and percentile; ascending, in the unit of `value`
+ [ranks [50, 75, 90, 95, 99]] // percentile only; this is the default
+ [timestamp <expr>] // milliseconds; default meta.timestamp, the span's end
+}
+```
+
+The entity constructors, usable inline in `scope` or in a `def`. Every name passes through the core module's naming
+rules, as a meter entity's does:
+
+| Constructor | Entity |
+|---|---|
+| `service(name, layer)` | a service in the layer |
+| `instance(service, instance, layer)` | a service instance |
+| `endpoint(service, endpoint, layer)` | an endpoint |
+| `serviceRelation(CLIENT \| SERVER, source, sourceLayer, dest, destLayer, componentId)` | a call between two services, each in its own layer; `componentId` is an `int`, normally `component(...)` |
+| `serviceInstanceRelation(CLIENT \| SERVER, sourceService, sourceInstance, sourceLayer, destService, destInstance, destLayer, componentId)` | a call between two instances |
+
+A `layer` argument is a string expression. A name that is not registered skips the block, with one warning per
+name; a `value` that does not parse as a number skips the block the same way. An entity held in a `def` has one
+shape: reassigning it with a different constructor is a compile error.
+
+The functions are the meter system's, named for what they do to the values of one minute:
+
+| `function` | Value | Meaning per minute per entity |
+|---|---|---|
+| `cpm` | number | the total of the values divided by the bucket's length in minutes, so hour and day rows read as a rate; `value 1` is calls per minute. The same number `core.oal`'s `cpm` computes; `sumPerMin` is accepted as an alias |
+| `sum` | number | the raw total; at hour and day level the totals add rather than average |
+| `avg` | number | the mean; `value meta.latency` is mean latency |
+| `max`, `min`, `latest` | number | |
+| `percent` | `match` condition | `matches * 10000 / total`, the `core.oal` `percent` scale; `match meta.statusCode != "ERROR"` is the success rate |
+| `apdex` | `value` and `status` | the `core.oal` `apdex`: thresholds from `service-apdex-threshold.yml` looked up by the entity's service name, satisfied under `T`, tolerated under `4T` |
+| `sumLabeled`, `avgLabeled`, `maxLabeled`, `minLabeled`, `latestLabeled`, `sumPerMinLabeled` | number, by `labels` | one series per label set; `labels status: attr("http.response.status_code", "http.status_code")` splits a count by status code |
+| `histogram` | number, by `buckets` | the observation counted in the first bucket whose bound is not below it; a value above the last bound lands in the last bucket |
+| `percentile` | number, by `buckets` | the same buckets, reduced to the `ranks` at query time |
+
+With `cpm`, `percent` and `apdex` a TAL metric named like an agent metric holds the same number in the same unit, so
+an alarm rule or a dashboard widget written for `service_sla` ports to `otlp_service_sla` by renaming the metric.
+
+### Sink
+
+`sink {}` persists the record the rule builds and needs an `outputType`; without a sink no record is written, and a
+`sink {}` in a rule with no `outputType` is a compile error. Its statements are LAL's: `sampler { rateLimit("<id>")
+{ rpm <n> } }`, shared by id across rules and spans, `dropper {}`, `enforcer {}` and `if`.
+
+### Persist
+
+`persist {}` decides the fate of the span itself, with the same statements as `sink {}`. Storing the incoming span
+is the receiver's default and most rules only want metrics, so a rule without `persist {}` abstains. A rule with
+`persist {}` votes: `dropper {}` and an unsampled `rateLimit` vote drop, `enforcer {}` votes keep and marks the span
+enforced, an empty `persist {}` votes keep. The span is stored when every rule that voted said keep and no span
+listener vetoed; a drop vote from one rule therefore beats an `enforcer {}` in another, and a rule that aborted did
+not vote.
+
+Two things follow from the span being the unit:
+
+- `rateLimit` counts spans, not traces: two spans of one trace can fall on different sides of the budget and a
+ stored trace can have spans missing. A rule that needs whole traces keys its decision on something every span of
+ the trace carries, or accepts partial traces.
+- `enforcer {}` also bypasses the receiver's head sampling. TAL votes before `otlpTraceSampleRate` is applied, and an
+ enforced span skips the trace-id check, the way a Zipkin `debug` span does. It does not skip
+ `otlpTraceMaxSpansPerSecond`, which stays the operator's ceiling. The bypass is per span, so at a low sample rate an
+ enforced slow statement is stored while the rest of its trace may not be, and an `enforcer {}` on a broad condition
+ turns head sampling off for everything it matches; it belongs behind a condition that is rare by construction, an
+ error status or a latency threshold.
+
+## Output Type
+
+A rule that declares `outputType` builds one record per span and writes it in `sink {}`, the way a LAL rule does.
+Every extractor statement whose name is not a keyword becomes a setter call on the record, validated at compile
+time; the standard fields `service`, `instance`, `endpoint` and `layer` are taken from `meta`, so the `service`
+statement names the record's service.
+
+- A `TALOutputBuilder` name, `SlowSQL` for the `DatabaseSlowStatement` record. Its fields are `id`, `statement` and
+ `latency`; `traceId`, `timestamp` and `layer` come from `meta`. The record shows on the database's slow-statement
+ panel when the record's service is named and layered as the database node in the topology.
+- The fully qualified class name of a `Source` subclass. The sink sets its time bucket from `meta.timestamp` and
+ hands it to the source receiver, so a rule can fill any `core.oal` source. The shipped rules do not use this, and
+ mixing `core.oal` entities with `otlp_*` ones for one fleet counts a service twice.
+
+## Address-named peers
+
+A CLIENT span names its peer by what it dialed, `server.address` and `server.port`, and the callee names itself by
+`service.name`; nothing on the OTLP wire ties the two, since the trace context carries no address. Without help, a
+fleet that does not set `service.peer.name` gets `product-catalog:3550` beside `product-catalog` in the service list and
+in the topology. Three mechanisms fold the address onto the service, and the shipped rule uses all three:
+
+- **`alias <address>`** in a SERVER span's rule registers the address the span was dialed at as a network address
+ alias of `meta.service`, the row the agent path derives from its propagation header. An HTTP server's
+ `server.address` and `server.port` are the `Host` the caller sent, so the caller's `resolveAlias` finds it. The
+ alias rows travel through storage and the core's alias cache, which reloads every 10 seconds, so the first calls
+ to a freshly seen address are still address-named, and the topology query folds those.
+- **`resolveAlias(address)`** on the CLIENT side answers, in this order: a host, or its first DNS label, that is the
+ name of a service this OAP node has seen spans from; the service an alias row names; the service whose SERVER span
+ this CLIENT span is the parent of, when the pairing below has seen it; else the address unchanged.
+- **Pairing** resolves the rest from the trace context: a SERVER span's `parentSpanId` is its caller's span id,
+ which needs no attribute convention on either side. Every SERVER span with a parent, and every CLIENT span
+ whose peer could not be named, becomes a fact; messaging spans take no part, since a CONSUMER span's parent is
+ the PRODUCER span and pairing them would alias the broker's address to the consumer. In a cluster the facts of one trace are
+ routed to the node that owns the trace, so the two halves meet wherever each arrived. A match learns the alias and
+ writes the row for every node. Facts wait 60 seconds for their other half; a callee that never reports, an
+ uninstrumented service or a dropped trace context, leaves its caller address-named, which is the honest answer.
+
+Two guards keep an alias honest. An address whose host names another service is never registered: a proxy that
+keeps the `Host` header hands `frontend-proxy:8080` to the `frontend` behind it, and that address stays the proxy's.
+And `resolveAlias` asks the known-service registry before the cache, so a row that did get through cannot redirect
+an edge away from a service that exists under that name.
+
+The source of a client edge is always the span's own `service.name`; a span emitted under a pseudo-service named after a backend, as HotROD's `mysql` spans are, is described under [Topology](../setup/backend/trace-analyzer.md#topology) in the operator guide.
+
+## Differences from LAL
+
+- No parser blocks. `text {}`, `json {}` and `yaml {}` give a log body structure; a span is already structured.
+- No `traceId`, `segmentId`, `spanId` or `timestamp` statements. The identifiers are facts of the span, readable as
+ `meta.traceId` and friends.
+- `abort {}` is allowed anywhere, and a `layer: auto` rule uses it to decline a span.
+- `tag` injects into the stored span, not into a record.
+- `alias` and `resolveAlias` exist, see above.
+- `metrics {}` declares a metric and emits one value; it does not hand a sample to another engine.
+- `persist {}` is new and decides the span's own fate; `sink {}` keeps LAL's meaning and needs an `outputType`.
+- Statements may be separated by `;` as well as by newlines, so a `metrics {}` block fits on one line.
+- `!` binds tighter than `&&` and `||`, as in Java: `!peer && hasAttr("x")` reads as `(!peer) && hasAttr("x")`.
diff --git a/docs/en/setup/backend/configuration-vocabulary.md b/docs/en/setup/backend/configuration-vocabulary.md
index 2be8492341..65e54238e2 100644
--- a/docs/en/setup/backend/configuration-vocabulary.md
+++ b/docs/en/setup/backend/configuration-vocabulary.md
@@ -172,6 +172,11 @@ It divided into several modules, each of which has its own settings. The followi
| log-analyzer | default | Log Analyzer. | SW_LOG_ANALYZER [...]
| - | - | lalFiles | The LAL configuration file names (without file extension) to be activated. Read [LAL](../../concepts-and-designs/lal.md) for more details. [...]
| - | - | malFiles | The MAL configuration file names (without file extension) to be activated. Read [LAL](../../concepts-and-designs/lal.md) for more details. [...]
+| trace-analyzer | default | Trace Analyzer. | SW_TRACE_ANALYZER [...]
+| - | - | talFiles | The TAL configuration file names (without file extension) to be activated, comma separated. Empty disables the span analysis while keeping the module, which the OpenTelemetry trace receiver requires. Read [TAL](../../concepts-and-designs/tal.md) for more details. [...]
+| - | - | dedupWindow | Seconds within which a span seen again on this node, by trace id and span id, is analyzed only once, so an exporter that retries a batch does not count a request twice. `0` keeps no set and treats every arrival as new. [...]
+| - | - | dedupCapacity | The most span ids the dedup set holds on this node while `dedupWindow` is above `0`; ignored at `0`. Size it as spans per second times `dedupWindow`, with headroom. About 150 bytes per entry. [...]
+| - | - | pairingSamplePercent | In a cluster, the percentage of traces whose client and server spans are routed to the trace's owner node to learn a network address alias from the pair. A single OAP node pairs every call and ignores this. [...]
| ai-agent-conversation | default | Conversations of long-lived AI agents landed by the AI Sessionizer as Session Data and Session Flow files over OTLP logs under the `AI_AGENT` layer. | SW_AI_AGENT_CONVERSATION | default | - |
| - | - | readWindow | How many Session Data files, or Session Flow rounds, one storage query fetches; a conversation is read batch by batch up to its head. | SW_AI_AGENT_CONVERSATION_READ_WINDOW | 16 |
| - | - | conversationListMaxLimit | The most rounds one list query reads before folding to one row per conversation. | SW_AI_AGENT_CONVERSATION_LIST_MAX_LIMIT | 10000 |
diff --git a/docs/en/setup/backend/otlp-trace.md b/docs/en/setup/backend/otlp-trace.md
index d935c4ac01..7c7e759da1 100644
--- a/docs/en/setup/backend/otlp-trace.md
+++ b/docs/en/setup/backend/otlp-trace.md
@@ -115,3 +115,10 @@ described in [TraceQL Service](../../api/traceql-service.md#otlp-native-trace).
The status module exposes the same queries with the execution trace for debugging under
`/debugging/query/otlp/api/search` and `/debugging/query/otlp/api/v2/trace`, see
[Status APIs](./admin-api/status.md).
+
+## Analysis
+
+Every accepted span also goes through the [Trace Analysis Language](../../concepts-and-designs/tal.md) rules of the
+`trace-analyzer` module, in both storage modes and before the head sampling and the rate limit above. The shipped
+rule file registers the services under the `OTLP_SERVICE` layer with their metrics, topology and slow statements;
+see [OpenTelemetry Trace Analysis](trace-analyzer.md) for the settings and for what it produces.
diff --git a/docs/en/setup/backend/trace-analyzer.md b/docs/en/setup/backend/trace-analyzer.md
new file mode 100644
index 0000000000..3fd0a803f6
--- /dev/null
+++ b/docs/en/setup/backend/trace-analyzer.md
@@ -0,0 +1,158 @@
+# OpenTelemetry Trace Analysis
+
+The `trace-analyzer` module runs the [Trace Analysis Language (TAL)](../../concepts-and-designs/tal.md) rules over
+every span the [OpenTelemetry trace receiver](otlp-trace.md) accepts, in both of its storage modes, and before the
+receiver's head sampling and rate limit, so the metrics count what the SDKs sent rather than what the OAP chose to
+store. With the defaults nothing needs to be enabled: once an OpenTelemetry SDK exports traces, its services, their
+metrics, their topology and their slow statements appear.
+
+## Configuration
+
+```yaml
+trace-analyzer:
+ selector: ${SW_TRACE_ANALYZER:default}
+ default:
+ # TAL rule files under `tal/`, without extension, comma separated. Empty disables span analysis while keeping
+ # the module, which the OTLP trace receiver requires.
+ talFiles: ${SW_TRACE_TAL_FILES:otlp-default}
+ # Spans seen within this window (seconds) are analyzed once, so an exporter that retries a batch after a
+ # transport timeout does not count a request twice. 0, the default, keeps no set at all and treats every
+ # arrival as new. Set it longer than the exporter's retry budget; the OTLP SDKs give up after about 30 s. The
+ # set is per OAP node: a retry that reaches another node is counted again.
+ dedupWindow: ${SW_TRACE_TAL_DEDUP_WINDOW:0}
+ # The most (traceId, spanId) pairs the set holds on this node while dedupWindow is above 0; ignored at 0.
+ # Size it as spans per second on this node times dedupWindow, with headroom: once full, the oldest entries
+ # drop before they expire and a late retry of one of them is counted. About 150 bytes per entry.
+ dedupCapacity: ${SW_TRACE_TAL_DEDUP_CAPACITY:1000000}
+ # In a cluster, the percentage of traces whose client and server spans are routed to the trace's owner node to
+ # learn a network address alias from the pair; both spans of a call share the trace id, so a pair is never
+ # split. An address only has to be learned once, after which every node resolves it from its cache, so a
+ # sample is enough: at 25 a new address is learned after about four calls. 100 routes every trace, at one
+ # small message per SERVER span across the cluster. A single node pairs every call and ignores this.
+ pairingSamplePercent: ${SW_TRACE_TAL_PAIRING_SAMPLE_PERCENT:25}
+```
+
+The rule files live under `config/tal/` of the distribution. To change what is measured, edit a file there or add
+one and list it in `talFiles`, then restart the OAP: the files are read at start. A rule file that does not compile,
+or that names a layer that is not registered, stops the OAP from starting with a message naming the rule.
+
+## What the shipped rule file produces
+
+`tal/otlp-default.yaml` holds two rules. `otlp-service` claims every span whose resource carries no `service.layer`,
+except the GenAI spans the GenAI analyzer already handles, and `otlp-slow-sql` writes a slow statement record for a
+database client span above 200 ms. Both read the OpenTelemetry semantic conventions with the current attribute
+names first and the deprecated spellings older SDKs still emit as fallbacks.
+
+### Layers
+
+| Layer | Holds | Registered by |
+|---|---|---|
+| `OTLP_SERVICE` | a service whose spans arrived over OTLP | every span's `service.name` |
+| `OTLP_VIRTUAL_DATABASE` | a database a client span names through `db.system.name` or `db.system` | the client's span |
+| `OTLP_VIRTUAL_CACHE` | a cache, the same way, for `redis`, `memcached` and the other cache systems | the client's span |
+| `OTLP_VIRTUAL_MQ` | a broker a producer or consumer span names through `messaging.system` | the producer's or consumer's span |
+
+The layers are separate from the agent path's `GENERAL` and `VIRTUAL_*` layers because their metrics come from a
+different engine under different names. A service id is its name plus the `normal` flag, not the layer, so a
+service that reports both agent segments and OTLP spans is one entity listed under both layers, and a database
+reached from both paths is one node.
+
+### Metrics
+
+Every metric carries the file's `otlp_` prefix. On the service and its edges:
+
+| Entity | Metrics |
+|---|---|
+| service | `otlp_service_cpm`, `otlp_service_resp_time`, `otlp_service_sla`, `otlp_service_apdex`, `otlp_service_percentile` |
+| instance, when the resource carries `service.instance.id` | `otlp_instance_cpm`, `otlp_instance_resp_time`, `otlp_instance_sla` |
+| endpoint, named `<method> <route>` for HTTP spans and by the span name otherwise | `otlp_endpoint_cpm`, `otlp_endpoint_resp_time`, `otlp_endpoint_sla`, `otlp_endpoint_percentile` |
+| the call a CLIENT or PRODUCER span makes | `otlp_service_relation_client_cpm`, `otlp_service_relation_client_resp_time`, `otlp_service_relation_client_sla` |
+| the call a root SERVER span receives, from the `User` node | `otlp_service_relation_server_cpm` |
+
+On the conjectured peers, from the client's span: `otlp_database_access_cpm`, `_resp_time` and `_sla`, and the
+`otlp_cache_access_*` and `otlp_mq_access_*` counterparts. The names follow the agent metrics of the same shape, so
+an alarm rule or a dashboard widget written for `service_sla` or `database_access_cpm` ports by renaming the
+metric. The `core.oal` metrics are not produced for these services; no dashboard template reads the `otlp_*`
+metrics yet, so query them through [MQE](../../api/metrics-query-expression.md) and reference them in alarm rules.
+
+The component of an edge, the protocol icon in the topology, comes from `rpc.system.name`, `rpc.system`,
+`db.system.name`, `db.system` or `messaging.system`, looked up in `component-libraries.yml` ignoring case; `grpc`
+finds `GRPC` and `connect_rpc` finds `Connect_RPC`. A system the catalog does not list shows as `Unknown`.
+
+A messaging `receive` poll is not a request: the rule drops a CLIENT or CONSUMER span whose `messaging.operation.type` (or the older `messaging.operation`) is `receive`, since the OpenTelemetry Java agent reports a blocking JMS receive as a CONSUMER span lasting the whole wait, which would otherwise count as a ten-second request on every poll. A `process` span, the message actually handled, counts as the consumer's request.
+
+### Topology
+
+A SERVER span with no parent is a call from the `User` node, which appears in the topology without a service list
+entry. A CLIENT span's peer is named by `service.peer.name`, or its deprecated spelling `peer.service`, when the SDK sets
+one, else by `server.address` and
+`server.port`, `net.peer.name` and `net.peer.port` on older SDKs, `peer.address` on an Envoy egress span, or the
+host and port of `url.full` or `http.url` when the SDK reports nothing else, as the Python `requests` instrumentation
+does. An
+address-named peer, `cart:7070` or `172.19.0.19:8080`, is folded onto the service it reaches by the three
+mechanisms described under [Address-named peers](../../concepts-and-designs/tal.md#address-named-peers): the
+server's own `alias`, the known-service registry, and the pairing of a call's two spans by the trace context. The
+first calls to a freshly seen address are address-named until the alias row has reached every node's cache, within
+about 10 seconds, and the topology query folds those.
+
+In a cluster the pairing routes the facts of a trace to the node that owns it, through the same channel the metrics
+use, so the two spans of a call meet wherever each arrived. `pairingSamplePercent` bounds that traffic: an address
+only has to be learned once, so a sample of the traces is enough, and a single node ignores the setting. While the
+cluster membership changes, a pair in flight can split and that address is learned one call later.
+
+The source of a client edge is the span's own `service.name`, never the service of the span it is nested under. An
+application that emits its database or cache spans from a tracer named after the backend, as Jaeger's HotROD demo
+does with `mysql` and `redis-manual`, therefore gets an edge from that pseudo-service to the peer, `mysql → mysql`,
+and a `mysql` entry in `OTLP_SERVICE` with no server metrics, while the service that made the call, `customer`,
+shows no edge to the database at all. The analyzer does not attribute a client span to its parent's service: the
+child is exported before its parent ends, so the parent is unknown when the child's metrics are written, and
+aggregated metrics cannot be moved afterwards. Instrumentations that wrap a driver emit the client span under the
+application's own service, and the edge comes out as expected. A database or broker reached without an address is still named: an embedded or in-process database by its
+system and namespace, `h2/mem-db`, and a broker whose client library hides the address, as the JMS API does, by
+its messaging system alone, `jms`. The queue or topic a message went to becomes an endpoint of that broker
+node, carrying `otlp_mq_destination_cpm`, `resp_time` and `sla`, so the virtual layer's list stays one row per
+broker while the destinations can still be ranked, and a consumer's handled messages draw the same broker as
+their caller. Such a node has no address for an alias to fold, so a broker that other clients reach by address
+keeps a second identity under that address. A client span that knows none of these, neither an address, a
+`service.peer.name`, a database system nor a messaging system, as the APISIX 2.15 proxy span and HotROD's Redis
+spans do, draws no peer node, and its errors reach no metric, since `service_sla` counts server spans.
+
+### Records
+
+`otlp-slow-sql` writes a `DatabaseSlowStatement` for a database client span whose latency is 200 ms or more, with the
+statement from `db.query.text` or `db.statement`, under the database node the topology names, and keeps the span
+behind it past the receiver's head sampling. The threshold is in the rule file; the agent path keys it by database
+type through `slowDBAccessThreshold`, and a deployment edits the rule to match.
+
+## Turning the analysis off
+
+A deployment that wants the OTLP traces stored and queried, and nothing derived from them, empties the rule file
+list:
+
+```yaml
+trace-analyzer:
+ selector: ${SW_TRACE_ANALYZER:default}
+ default:
+ talFiles: ${SW_TRACE_TAL_FILES:}
+```
+
+or sets `SW_TRACE_TAL_FILES` to an empty string. With no rule installed a span costs the analyzer nothing: no
+metric, no service or topology entry, no slow statement record, no pairing fact, and in a cluster no pairing
+traffic. The receiver's storage path is unchanged, so the traces are still stored in the mode `otlpTraceStorage`
+selects and still served to TraceQL.
+
+Removing the module altogether, with `selector: -` or `SW_TRACE_ANALYZER=-`, has the same effect: the OpenTelemetry
+trace receiver declares the module as a requirement only when it is loaded, and without it the receiver stores
+every span and analyzes none. The difference is what stays resident: with an empty `talFiles` the module and its
+services exist and a rule file can be listed again with a restart; with `-` nothing of it is loaded.
+
+To keep part of the analysis, put the rules you want in a file of your own under `config/tal/` and list only that
+file. The two shipped rules are independent: `otlp-slow-sql` alone writes the slow statement records and keeps the
+spans behind them, without registering any service or metric.
+
+## Deduplication
+
+An OTLP exporter retries a batch after a transport timeout, and the OAP may have accepted the first attempt, so a
+retried span would count a request twice. `dedupWindow` keeps a per-node set of the span ids seen within the
+window and analyzes a span once; it is off by default because it costs memory per span and the OTLP logs path does
+not deduplicate either. The set is per OAP node, so a retry that lands on another node is counted again.
diff --git a/docs/en/swip/SWIP-otlp-trace-analysis-language.md b/docs/en/swip/SWIP-otlp-trace-analysis-language.md
new file mode 100644
index 0000000000..ddb28d390d
--- /dev/null
+++ b/docs/en/swip/SWIP-otlp-trace-analysis-language.md
@@ -0,0 +1,1518 @@
+# Trace Analysis Language (TAL) for OTLP Spans
+
+## Motivation
+
+OTLP spans reach OAP over `TraceService/Export` and `POST /v1/traces`, are handed to the phase-one `SpanListener`s,
+and are then stored, either as Zipkin spans today or natively as
+[the native OTLP trace storage proposal](SWIP-otlp-native-trace.md) describes. Nothing in that path turns a span
+into a service, an instance, an endpoint, a topology edge or a metric. An OpenTelemetry SDK user sees traces and
+nothing else.
+
+[The source-mapping proposal](SWIP-otlp-trace-metrics.md) closes the gap by mapping each span onto the `Source`
+objects the agent trace analyzer emits, `Service`, `ServiceRelation`, `DatabaseAccess` and the rest, so the
+unchanged `core.oal` produces the agent metrics for OTLP services too. The mapping is driven by a YAML rule file
+whose vocabulary, `aliases`, `requestType.precedence`, `peers.virtual`, `callers`, is a purpose-built schema: every
+question the mapping must answer is a fixed key with fixed semantics, and every question it does not anticipate is
+a Java change. The set of things a span can produce is fixed to the sources `core.oal` knows, the metric set is
+fixed to what `core.oal` defines, and the rule file is loaded once at boot with no hot update and no debugger.
+
+SkyWalking already has the shape this problem needs. Logs arriving from agents, Fluent Bit, Envoy ALS and OTLP are
+not mapped by a schema; they are analyzed by LAL, a small compiled language in which a rule reads the record,
+decides what it is, extracts fields, emits metrics and votes on persistence. LAL rules are hot-updated by the
+runtime-rule plugin and inspected live by the DSL debugger. Underneath every non-OAL metric in OAP sits one engine,
+`MeterSystem`: a metric is a name, a function such as `sum`, `avg` or `sumHistogramPercentile`, and an entity
+scope; MAL is one rule surface over it, and `Analyzer` is the code that builds the `MeterEntity`, emits the entity
+traffic and hands the value to `MeterSystem`.
+
+This proposal gives OTLP spans the same treatment: a **Trace Analysis Language (TAL)** whose unit of evaluation is
+one span with its resource and instrumentation scope, exactly as LAL's unit is one log record. A TAL rule reads
+the span through typed accessors and the semantic-convention attributes through helper functions, decides whether
+the span is its concern, extracts identity, and declares its metrics directly: name, function, entity scope and
+value, in the rule, compiled to direct `MeterSystem` calls. No `Source` is emitted, `core.oal` is not involved, no
+MAL rule file is needed, and the semantic-convention knowledge lives in a rule file an operator can read, edit,
+hot-update and debug.
+
+Why not route the values through MAL, as LAL does with `log-mal-rules`: a span yields one point per metric, not a
+family of samples. MAL's strength is family algebra over scrape-shaped data, `rate`, `increase`, relabeling,
+combining series, and none of it applies to a single point. What a span metric needs is a function, a scope and,
+for percentiles, a bucket list, and the core implements all three. Putting them in the rule removes a second file,
+a second syntax, the `SampleFamily` intermediate and its edge cases, and makes every metric a compile-time fact the
+runtime-rule and debugging tooling can reason about.
+
+Two LAL mechanisms carry over unchanged in spirit. `inputType` makes the OTLP span the default input rather than
+the only one: a rule can declare the Zipkin span as its input and the same language, routing and tooling apply to
+traces arriving over the Zipkin protocol, through the same typed-input SPI that lets Envoy access logs and TCP
+access logs share one LAL layer. `outputType` lets a rule write a record instead of, or as well as, metrics: a slow
+database statement from a span that carried `db.query.text`, through the same `SlowSQL` builder the MySQL and
+PostgreSQL slow-log LAL rules use today.
+
+What TAL is not: it is per-span. It never sees two spans of a trace together, so a server span cannot learn its
+caller from the client span, and a consumer cannot see its producer.
+
+This proposal is an alternative to the source-mapping proposal, not a companion: both close the same gap and a
+deployment should adopt one. It is independent of the native storage proposal and works with either
+`otlpTraceStorage` mode, because it runs before conversion and before storage.
+
+## Architecture Graph
+
+```text
+OTLP/gRPC :11800 TraceService/Export ──┐ Zipkin HTTP :9411 / Kafka ──┐
+OTLP/HTTP :12800 POST /v1/traces ──┤ │
+ v v
+ OpenTelemetryTraceHandler.processExport (receiver-otel) SpanForward.send (receiver-zipkin)
+ │ per resource: attributes -> strings, service name, │ before head sampling, per zipkin2.Span:
+ │ instance, service.layer │ doAnalysis(SpanMetadata, zipkin2.Span) inputType: zipkin
+ │ per span: │ drop vetoed spans, putTag the injected tags
+ ├─ SpanListenerManager.notifyOTLPPhase (existing listeners) │ (reserved: the Zipkin path is not wired in this proposal)
+ ├─ doAnalysis(SpanMetadata, Span, resourceAttributes) inputType: otlp (default)
+ │ │ │
+ │ v v
+ │ trace-analyzer module oap-server/analyzer/trace-analyzer ITraceAnalyzerService
+ │ SpanFilterListener.Factory: Layer -> (ruleName -> compiled TAL rule), plus `layer: auto` rules
+ │ │ at compile: every `metrics {}` -> MeterSystem.create(name, function, scopeType)
+ │ │ `outputType` -> TALOutputBuilder or Source subclass, setters validated
+ │ │ per span, for every rule of the span's layer whose inputType matches the object:
+ │ │ execute(FilterSpec, ExecutionContext) compiled bytecode, no reflection
+ │ │ filter { if (...) abort {}
+ │ │ extractor { service/instance/endpoint/layer, tag, <output fields>, metrics {} }
+ │ │ sink { ... } // the output record
+ │ │ persist { ... } } // the span itself
+ │ │
+ │ ├─ metrics {} ──> MeterEntity ──> EntityTrafficGenerator.generate(entity) (moved to core, shared with MAL)
+ │ │ │ ServiceTraffic / InstanceTraffic / EndpointTraffic
+ │ │ │ ServiceRelationClientSideMetrics / ServerSideMetrics (topology)
+ │ │ v
+ │ │ MeterSystem.buildMetrics(name, type).accept(entity, value) -> doStreamingCalculation
+ │ │ otlp_* metrics, minute buckets, L1 aggregation as for MAL
+ │ │
+ │ ├─ sink {} ──> outputType builder.complete(SourceReceiver) e.g. SlowSQL -> DatabaseSlowStatement
+ │ │
+ │ └─ persist {} votes + tag statements ──> SpanAnalysisResult{persist, enforced, additionalTags}
+ │
+ ├─ persist = listenerResult.shouldPersist && analysisResult.persist
+ ├─ tags = listenerResult.additionalTags + analysisResult.additionalTags
+ ├─ enforced = persist && analysisResult.enforced // the forward skips the trace-id head sampling for it
+ v
+ Zipkin conversion -> SpanForward.send | OTLPSpanForward -> otlp_span (enforced spans skip head sampling, not the rate limit)
+
+Operator surfaces (existing modules, extended):
+ runtime-rule POST /runtime/rule/addOrUpdate?catalog=tal hot update, metric and output shape guard, cluster convergence
+ dsl-debugging POST /dsl-debugging/session?catalog=tal live capture of input, statements, emitted metrics and records
+ SW_DYNAMIC_CLASS_ENGINE_DEBUG=true {skywalking}/tal-rt/*.class + *.java
+```
+
+## Proposed Changes
+
+### 1. Module and configuration
+
+A new analyzer module, `oap-server/analyzer/trace-analyzer`, `TraceAnalyzerModule.NAME = "trace-analyzer"`,
+built the way `log-analyzer` is built. Its services:
+
+| Service | Purpose |
+|---|---|
+| `ITraceAnalyzerService` | `SpanAnalysisResult doAnalysis(SpanMetadata meta, Span span, Map<String, String> resourceAttributes)`, called by the OTLP trace handler per span |
+| `SpanFilterListener.Factory` | the registry of compiled TAL rules keyed by `(Layer, ruleName)` plus the `layer: auto` set; `compile`, `addOrReplace`, `remove`, `suspend`, `resume`, `find`, the same surface `LogFilterListener.Factory` exposes to the runtime-rule plugin |
+
+`requiredModules()` is `CoreModule.NAME`, `ConfigurationModule.NAME` and `StorageModule.NAME`, for the same reasons
+`LogAnalyzerModuleProvider` declares them: `MeterSystem`, `NamingControl` and `IComponentLibraryCatalogService`
+come from core, `MeterSystem.create` at compile needs the storage model installer, and the runtime-rule override
+resolver consulted while loading static rules needs the management table to exist. The module depends on
+`receiver-proto` for the OTLP `Span` proto, as `log-analyzer` already does for the logging protos.
+
+```yaml
+trace-analyzer:
+ selector: ${SW_TRACE_ANALYZER:default}
+ default:
+ # TAL rule files under `tal/`, without extension, comma separated. Empty disables span analysis.
+ talFiles: ${SW_TRACE_TAL_FILES:otlp-default}
+ # Spans seen within this window (seconds) are analyzed once, so an exporter that retries a batch after a
+ # transport timeout does not count a request twice. 0, the default, keeps no set at all and treats every
+ # arrival as new, which is what OTLP logs do today. Set it longer than the exporter's retry budget; the OTLP
+ # SDKs give up after about 30 s. The set is per OAP node: a retry that reaches another node is counted again.
+ dedupWindow: ${SW_TRACE_TAL_DEDUP_WINDOW:0}
+ # The most (traceId, spanId) pairs the set holds on this node while dedupWindow is above 0; ignored at 0.
+ # Size it as spans per second on this node times dedupWindow, with headroom: once full, the oldest entries
+ # drop before they expire and a late retry of one of them is counted. About 150 bytes per entry.
+ dedupCapacity: ${SW_TRACE_TAL_DEDUP_CAPACITY:1000000}
+ # In a cluster, the percentage of traces whose client and server spans are routed to the trace's owner node to
+ # learn a network address alias from the pair; both spans of a call share the trace id, so a pair is never
+ # split. An address only has to be learned once, after which every node resolves it from its cache, so a
+ # sample is enough: at 25 a new address is learned after about four calls. 100 routes every trace, at one
+ # small message per SERVER span across the cluster. A single node pairs every call and ignores this.
+ pairingSamplePercent: ${SW_TRACE_TAL_PAIRING_SAMPLE_PERCENT:25}
+```
+
+`talPath` exists as `lalPath` does and defaults to `tal`. The module is present by default so that the shipped rule
+produces entities and metrics for OTLP traces out of the box; setting `talFiles` empty turns the analysis off while
+keeping the module, and `selector: -` removes it, which `receiver-otel` tolerates by storing the spans without
+analysis. The new default is added to
+`test/e2e-v2/cases/storage/expected/config-dump.yml`.
+
+`OtelMetricReceiverProvider.requiredModules()` gains `TraceAnalyzerModule.NAME`, declared only when the module is
+loaded, so that the analyzer starts before the receiver when present and a deployment that removed it still boots;
+the trace handler resolves `ITraceAnalyzerService` on first use and skips the analysis when the module is absent.
+Today the OTLP handler finds `ZipkinReceiverModule` lazily without declaring it, which is the pattern this
+repository asks not to repeat.
+
+Input kinds are contributed through an SPI, `TALSourceTypeProvider`, discovered with `ServiceLoader` the way
+`LALSourceTypeProvider` is. The module registers the OTLP provider, which is the only one this proposal ships; a
+Zipkin provider is the reserved extension of [section 2.2](#22-zipkin--reserved-not-in-scope). See
+[section 3.2](#32-what-a-rule-can-read).
+
+### 2. Receiver integration
+
+#### 2.1 OTLP
+
+`OpenTelemetryTraceHandler.processExport` already computes the resource attribute map, the service name with
+its fallbacks and the scope name and version, and already runs `notifyOTLPPhase` per span. It gains one call per
+span, after the listeners and before conversion:
+
+```java
+final SpanMetadata meta = SpanMetadata.of(serviceName, resourceTags, scopeSpans.getScope(), span);
+final SpanAnalysisResult analysis = traceAnalyzerService().doAnalysis(meta, span, resourceTags);
+if (!otlpResult.isShouldPersist() || !analysis.isPersist()) {
+ continue;
+}
+// merge otlpResult.getAdditionalTags() and analysis.getAdditionalTags() into spanTags, last writer wins
+```
+
+`analysis.isEnforced()` travels with the span to the forward: `OTLPSpanForward.send` gains an `enforced` argument,
+and in the Zipkin storage mode the converted span is forwarded as today. The OTLP forward skips the trace-id
+head sampling for an enforced span and still count it against `maxSpansPerSecond`, see
+[section 3.3](#33-filter-extractor-sink-persist).
+
+`SpanMetadata` lives in `server-core`, package `org.apache.skywalking.oap.server.core.trace`, next to
+`OTLPSpanReader`, and is the span's counterpart of `LogMetadata`: the derived, protocol-neutral view a rule reads
+as `meta.*` and the extractor may overwrite.
+
+| Field | Populated by the receiver as |
+|---|---|
+| `service` | `service.name`, then the fallbacks `extractZipkinServiceName` already applies, `faas.name` and `process.executable.name` |
+| `serviceInstance` | `service.instance.id`, then `service.instance`, the order the OTLP logs handler uses; empty when absent |
+| `endpoint` | `Span.name` |
+| `layer` | the `service.layer` resource attribute, empty when absent; drives rule routing, see [section 3.1](#31-rule-files-and-layer-routing) |
+| `kind` | `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER`, `INTERNAL`, `UNSPECIFIED`: the proto enum name without its prefix |
+| `statusCode`, `statusMessage` | `UNSET`, `OK`, `ERROR`, and `Status.message` |
+| `startTime`, `timestamp` | `start_time_unix_nano / 1_000_000` and `end_time_unix_nano / 1_000_000`; `timestamp` is the default metric time |
+| `latency` | `end - start` in nanoseconds rounded to milliseconds, clamped to `[0, Integer.MAX_VALUE]`, as `setPublicAttrs` does for agents |
+| `traceId`, `spanId`, `parentSpanId` | lowercase hex; `parentSpanId` empty for a root |
+| `root` | `parentSpanId` is empty |
+| `scopeName`, `scopeVersion` | `InstrumentationScope.name` and `version` |
+
+`SpanAnalysisResult` carries `persist`, `enforced` and `additionalTags`. The merge rule with the listeners is the
+one `SpanListenerManager` uses among listeners: any veto drops the span, tags merge last-writer-wins. `enforced` is
+true when a rule's `enforcer {}` fired and the span is persisted; it asks the forward to skip the trace-id head
+sampling. TAL runs on every span regardless of head sampling and rate limiting, which `SpanForward` and
+`OTLPSpanForward` apply afterwards, so metrics count what the SDK sent, not what OAP chose to store. That is the
+ordering the agent path has.
+
+A resource without a resolvable service name is skipped before TAL, as it is skipped today. In the Zipkin storage
+mode the converted spans go to `SpanForwardService.send` unchanged; nothing analyzes them twice, because the
+Zipkin receiver runs no rules — see [section 2.2](#22-zipkin--reserved-not-in-scope).
+
+#### 2.2 Zipkin — reserved, not in scope
+
+**This section describes a capability the design reserves, not work this proposal delivers.** TAL ships analyzing
+OTLP spans only; the Zipkin receiver is untouched, and a Zipkin span reaches no rule. What follows is the shape
+the integration takes when a deployment asks for it, recorded here so nothing in the engine has to change then.
+
+What already makes it possible: `inputType` is a list resolved against the registered `TALSourceTypeProvider`
+aliases, so a Zipkin provider declaring `alias() = "zipkin"` and `inputType() = zipkin2.Span` plugs in through
+`META-INF/services` alone, and a rule opts in by writing `inputType: otlp, zipkin`. `SpanMetadata.of(zipkin2.Span)`,
+the adapter below, is already in `server-core`. Neither the grammar, the compiler nor the runtime knows which
+protocol a span arrived over.
+
+What the integration would add: `SpanForward.send` — what the Zipkin HTTP and Kafka collectors call — gains one
+loop before `getSampledTraces`, so that, as on the OTLP side, metrics count what was sent rather than what was
+stored:
+
+```java
+final List<Span> analyzed = new ArrayList<>(spanList.size());
+final Set<Span> enforced = new HashSet<>();
+for (final Span span : spanList) {
+ final SpanMetadata meta = SpanMetadata.of(span); // the Zipkin adapter
+ final SpanAnalysisResult analysis = traceAnalyzerService().doAnalysis(meta, span, Collections.emptyMap());
+ if (!analysis.isPersist()) {
+ continue;
+ }
+ final Span stored = analysis.getAdditionalTags().isEmpty() ? span : withTags(span, analysis.getAdditionalTags());
+ analyzed.add(stored);
+ if (analysis.isEnforced()) {
+ enforced.add(stored);
+ }
+}
+final var sampledTraces = getSampledTraces(analyzed, enforced);
+```
+
+`withTags` is `span.toBuilder().putTag(k, v).build()`, because `zipkin2.Span` is immutable. When no rule declares
+the Zipkin input, the factory returns no rules for the object and the loop costs one `SpanMetadata` per span.
+`getSampledTraces` gains the enforced set: a span in it passes the trace-id check the way a span with Zipkin's
+`debug` flag does today, but unlike `debug` it still takes a permit from the rate limiter. `sendAnalyzed` is the
+same method without the loop, taking the analyzed spans and the enforced set. The phase-two `notifyZipkinPhase` for
+the existing listeners stays where it is, after conversion to `ZipkinSpan`.
+
+The Zipkin adapter fills `SpanMetadata` from the wire object:
+
+| Field | From `zipkin2.Span` |
+|---|---|
+| `service` | `localServiceName()`; `Unknown` when empty, as `SpanForward` names it today |
+| `serviceInstance` | empty; Zipkin has no instance identity |
+| `endpoint` | `name()` |
+| `layer` | empty, so `layer: auto` rules apply; Zipkin carries no `service.layer` |
+| `kind` | `kind().name()`; `UNSPECIFIED` when absent, which is how an OTLP `INTERNAL` span reads after conversion |
+| `statusCode`, `statusMessage` | `ERROR` when the `error` tag is present, the Zipkin convention, and its value; `UNSET` otherwise |
+| `startTime`, `timestamp`, `latency` | `timestampAsLong()` and `duration()` in microseconds, converted to milliseconds; `timestamp` is start plus duration |
+| `traceId`, `spanId`, `parentSpanId`, `root` | `traceId()`, `id()`, `parentId()`, already hex; root when `parentId()` is null |
+| `scopeName`, `scopeVersion` | empty |
+
+`attr()` and `hasAttr()` read `tags()`; `resource()`, `scopeAttr()`, `event()` and `eventAttr()` return empty for
+this input, since Zipkin has no resource, no scope and annotations are not events. A rule written against `meta`
+and `attr()` therefore runs unchanged on both inputs, which is what the shipped rule does.
+
+### 3. The language
+
+TAL is LAL with the log-specific parts removed and span-specific parts added. Anyone who has written a LAL rule
+can read a TAL rule.
+
+#### 3.1 Rule files and layer routing
+
+```yaml
+# tal/<file>.yaml
+metricPrefix: otlp # every metric declared in this file is stored as <metricPrefix>_<name>
+layerDefinitions: # optional, same contract as LAL and MAL: registered through Layer.register before compile
+ - name: IOT_FLEET
+ ordinal: 1000
+ normal: true
+rules:
+ - name: otlp-service # unique within its layer
+ layer: auto # a Layer name, or `auto`
+ inputType: otlp # optional; a provider alias or FQCN, or a comma-separated list of them. Default `otlp`
+ outputType: SlowSQL # optional; a TALOutputBuilder name, or the FQCN of a Source subclass. No default
+ dsl: |
+ filter { ... }
+```
+
+Routing follows LAL exactly. A span whose resource carries `service.layer` is evaluated by the rules declared for
+that layer, and by nothing else; an unknown layer name is logged and the span is not analyzed. A span without
+`service.layer` is evaluated by the `layer: auto` rules; a rule that does not `abort {}` has claimed the span and
+must set `layer` in its extractor, or the rule's output is discarded with a warning. If no auto rule claims the
+span, no analysis happens. There is no fallback to `GENERAL`: `GENERAL` is the agent layer, and putting OTLP spans
+there without `core.oal` metrics would produce services with empty dashboards, see
+[section 6](#6-the-otlp_service-layer).
+
+Rules for one layer run in file order, each with its own `ExecutionContext` and its own copy of `SpanMetadata`, so
+a rule that overwrites `service` for its record does not change what the next rule reads. Each rule decides
+independently.
+
+#### 3.2 What a rule can read
+
+**Inputs.** `inputType` names the object the rule reads. Each input kind is a `TALSourceTypeProvider`:
+
+```java
+public interface TALSourceTypeProvider {
+ String alias(); // `otlp`, `zipkin`; what a rule writes in inputType
+ Class<?> inputType(); // io.opentelemetry.proto.trace.v1.Span, zipkin2.Span
+ SpanAttributeReader attributes(Object input); // backs attr(), hasAttr(), resource(), scopeAttr(), event(), eventAttr()
+ String renderInput(Object input); // the debugger's input payload, OTLP/JSON or Zipkin JSON
+}
+```
+
+The module ships the `otlp` provider; a `zipkin` one is reserved, see [section 2.2](#22-zipkin--reserved-not-in-scope).
+A rule without `inputType` is an `otlp` rule, and a rule names exactly one input, because the `span` root's type
+is the input's type; `compile` refuses a rule that lists more. Serving one rule to several inputs, for a rule that
+reads the span only through `meta` and the functions, is reserved with the Zipkin provider.
+At analysis time, `SpanFilterListener.parse` runs a rule only when the incoming object is an instance of one of its
+declared input types, the `isInstance` guard `LogFilterListener.parse` uses to keep HTTP and TCP access-log rules
+apart under one layer. Routing by layer and by input compose: a Zipkin span, with its empty layer, reaches the auto
+rules that declare `zipkin`.
+
+An agent segment's `SpanObject` could be a third provider through the same SPI. It is not proposed: the agent path
+has `RPCAnalysisListener` and `core.oal`, and nothing in this design needs to touch them.
+
+**Roots.** Two roots replace LAL's `parsed` and `log`:
+
+| Root | Type | Resolved | Examples |
+|---|---|---|---|
+| `span` | the declared input type; `io.opentelemetry.proto.trace.v1.Span` by default | at compile time, getter and method chains generated as direct calls, the way LAL resolves `parsed.*` on `HTTPAccessLogEntry` | OTLP: `span.name`, `span.traceState`, `span.status.message`, `span.eventsCount`, `span.linksCount`; Zipkin: `span.remoteServiceName()`, `span.localEndpoint()?.ipv4()`, `span.shared()` |
+| `meta` | `SpanMetadata` | at compile time | `meta.service`, `meta.kind`, `meta.statusCode`, `meta.latency`, `meta.root`, `meta.scopeName` |
+
+`span.kind` and `span.status.code` are proto enums and read awkwardly; `meta.kind` and `meta.statusCode` are the
+string forms meant for conditions, and they mean the same thing on every input.
+
+**Functions.** Attributes are `repeated KeyValue` on the OTLP wire and a tag map on the Zipkin wire, so they are
+reached through functions the input's provider backs, all null-safe and returning `""` when absent:
+
+| Function | Returns |
+|---|---|
+| `attr(key, ...)` | the first present span attribute among the keys, rendered as a string with the receiver's `AnyValue` rules: scalars as text, arrays joined by `,`, kvlists as JSON, bytes as base64. Several keys let one rule serve SDKs on different semantic-convention versions: `attr("db.system.name", "db.system")` |
+| `hasAttr(key, ...)` | whether any of the keys is present on the span |
+| `resource(key, ...)` | the same over the resource attributes; `resource("telemetry.sdk.language")` |
+| `scopeAttr(key, ...)` | the same over the instrumentation scope attributes |
+| `event(name)` | the first `Span.Event` with that name, or `null`; `event("exception")?.timeUnixNano` |
+| `eventAttr(name, key, ...)` | an attribute of that event; `eventAttr("exception", "exception.type")` |
+| `component(name)` | the component id from `component-libraries.yml` as an `int`, matched exactly and then ignoring case through the catalog's `getComponentIdIgnoreCase`, so `attr("rpc.system.name", "rpc.system")`, `grpc`, finds `GRPC`, and `postgresql` finds `PostgreSQL`; `0`, the `Unknown` component, when nothing matches. Meant for the relation scopes |
+| `resolveAlias(address)` | the service the address names: a host, or its first DNS label, that is the name of a service this OAP has seen spans from; else the service a SERVER span registered the address for through the `alias` statement, read from the core's `NetworkAddressAliasCache`; else the service whose SERVER span this CLIENT span is the parent of, when that span has already been analyzed here, which also learns the alias row; else the address unchanged, and the span waits for it [...]
+| `urlHost(url)` | the authority of a URL, `host` or `host:port`, without scheme, user info, path, query or fragment; empty when the value has none. The shipped rule's last fallback for a CLIENT span's peer, for SDKs that name the target only as `url.full` or `http.url`, the Python `requests` instrumentation among them |
+| `toJson(expr)`, `toJsonArray(expr)` | as in LAL |
+
+The runtime helper indexes a span's attributes into a map on the first `attr()` call and hands the index to the
+next rule that runs on the same span, so a span costs one pass over its attribute list however many rules and
+lookups read it.
+
+#### 3.3 Filter, extractor, sink, persist
+
+```text
+filter {
+ <if / def / abort>*
+ extractor {
+ def <name> = <expr> [as <Type>] // any value, including an entity from section 3.4
+ service | instance | endpoint | layer <expr> // overwrite meta.*; also the record's standard fields
+ <field> <expr> [as <Type>] // output field of the outputType, section 3.5
+ tag '<key>': <expr> // injected into the persisted span
+ alias <expr> // the address this span was dialed at, section 6
+ metrics { ... } // section 3.4
+ if (...) { ... } else if (...) { ... } else { ... }
+ abort {}
+ }
+ sink { // the record declared by outputType, as in LAL
+ sampler { rateLimit("<id>") { rpm <n> } } // shared by id across rules and spans, as in LAL
+ dropper {}
+ enforcer {}
+ if (...) { ... }
+ }
+ persist { // the span itself; same statements as sink
+ ...
+ }
+}
+```
+
+Differences from LAL, all deliberate:
+
+- **No parser blocks.** `text {}`, `json {}` and `yaml {}` exist to give a log body structure; a span is already
+ structured. `inputType` selects among typed inputs, it does not select a parser.
+- **No `traceId`, `segmentId`, `spanId`, `timestamp` statements.** The identifiers are facts of the span, readable
+ as `meta.traceId` and friends, not things to extract. An output builder that needs them reads `meta`.
+- **`abort {}` is allowed anywhere**, at filter level and inside `extractor`, `sink` and `persist` bodies, and stops
+ the rule for this span. In `layer: auto` mode it means "not mine", as in LAL.
+- **`tag` injects into the span, not into a record.** The key and value are appended to the persisted span as a
+ string attribute, the way `SpanListenerResult.additionalTags` are appended today. This is how GenAI's estimated
+ cost reaches the stored span; a TAL rule can do the same for a derived field, for instance a normalized route.
+- **`alias <address>` registers a network address alias for the span's service**: the `NetworkAddressAliasSetup`
+ row the agent path derives from the `sw8` header, so a CLIENT span's `resolveAlias(peer)` lands its edge on this
+ service rather than on a node named by the address. An address whose host names another service is skipped.
+ Allowed at filter level and in `extractor`. See [section 6](#6-the-otlp_service-layer).
+- **`metrics {}` declares a metric and emits one value**, see [section 3.4](#34-the-metrics-block). It does not
+ emit a sample for another engine to aggregate.
+- **`sink {}` keeps LAL's meaning and needs an `outputType`.** It persists the record the rule builds, and without
+ it no record is written. A rule with no `outputType` has no record, so `sink {}` there is a compile error rather
+ than a silent no-op.
+- **`persist {}` is new and decides the span's own fate.** Persistence of the incoming span is the receiver's
+ default, and most TAL rules only want metrics, so a rule without `persist {}` abstains. A rule with `persist {}`
+ votes: `dropper {}` and an unsampled `rateLimit` vote drop, `enforcer {}` votes keep regardless of the samplers in
+ the same rule and marks the span enforced, an empty `persist {}` votes keep. The span is persisted when every rule
+ that voted said keep and no phase-one listener vetoed; a drop vote from another rule therefore beats an
+ `enforcer {}`, and `enforced` is only set on a span that is persisted. A rule that aborted did not vote. The two
+ blocks are separate because a slow-statement rule wants both: write the record, and force-keep the span that
+ produced it.
+- **`persist {}` samples spans, not traces.** `rateLimit` is LAL's `RateLimitingSampler`: one counter per id, kept
+ while the counter is below `rpm`, reset every minute, shared by every rule and span that uses the same id. It
+ counts spans, so two spans of one trace can fall on different sides of the budget and a sampled trace can be
+ stored with spans missing. The receiver's head sampling keeps or drops whole traces because it hashes the trace
+ id; `persist {}` does not, and a rule that needs whole traces has to key its decision on something trace-wide,
+ such as `enforcer {}` on a condition every span of the trace carries, or accept partial traces.
+- **`enforcer {}` also bypasses the receiver's head sampling.** TAL votes before `SpanForward` and
+ `OTLPSpanForward` apply `sampleRate` and `maxSpansPerSecond`. An enforced span skips the trace-id check, so
+ a span an `enforcer {}` kept is stored whatever `sampleRate` says, the way a Zipkin `debug` span is today. It
+ does not skip the rate limit: `maxSpansPerSecond` is the operator's ceiling on what the OAP accepts at all, and
+ a rule must not be able to lift it. Two limits follow. The bypass is per span: the other spans of the same trace
+ still follow the trace-id hash, so at a low `sampleRate` an enforced slow statement is stored while the rest of
+ its trace may not be; a whole trace can only be kept by enforcing every span of it, which a head decision cannot
+ know about in advance. And an `enforcer {}` on a broad condition turns head sampling off for everything it
+ matches, so it belongs behind a condition that is rare by construction, an error status or a latency threshold.
+- **Statements may be separated by `;`** as well as by newlines, so a `metrics {}` block fits on one line.
+
+Everything else, `def` with type inference and Java casts, `if` / `else if` / `else`, the condition operators,
+arithmetic and string concatenation with `+`, safe navigation `?.`, string interpolation in `rateLimit` ids, is
+LAL's grammar unchanged, with one precedence fix: `!` binds tighter than `&&` and `||`, so `!peer && hasAttr("x")`
+reads as `(!peer) && hasAttr("x")`, as in Java. LAL's grammar lists `AND` before `NOT`, which in an ANTLR
+left-recursive rule parses the same text as `!(peer && hasAttr("x"))`; the shipped LAL rules do not combine the two,
+and that grammar is left as it is.
+
+#### 3.4 The `metrics` block
+
+```text
+metrics {
+ name "<metric>" // literal; stored as <metricPrefix>_<metric>
+ scope <entity> // an entity constructor, or a `def` holding one
+ function <function> // literal, see the table
+ value <expr> // the observation; a number, or a string that parses as one. Not used by percent
+ [match <condition>] // percent only, required: the span counts as a match when true
+ [status <condition>] // apdex only, required: the span counts as successful when true
+ [labels k: v, ...] // required by the *Labeled functions, forbidden otherwise
+ [buckets [n, n, ...]] // required by histogram and percentile; ascending, in the unit of `value`
+ [ranks [50, 75, 90, 95, 99]] // percentile only; this is the default
+ [timestamp <expr>] // milliseconds; default meta.timestamp, the span's end
+}
+```
+
+`name`, `function` and the constructor used in `scope` are literals, so the compiler knows every metric a rule
+declares and its shape before a span arrives. The entity constructors, usable inline in `scope` or in a `def`:
+
+| Constructor | Builds | Notes |
+|---|---|---|
+| `service(name, layer)` | `MeterEntity.newService` | `layer` is a string expression resolved at runtime through `Layer.valueOf`; a name that is not registered skips the block, see below |
+| `instance(service, instance, layer)` | `newServiceInstance` | properties are a follow-up |
+| `endpoint(service, endpoint, layer)` | `newEndpoint` | |
+| `serviceRelation(CLIENT \| SERVER, source, sourceLayer, dest, destLayer, componentId)` | `newServiceRelation` with two layers, see [section 5](#5-metrics-through-metersystem) | `componentId` is an `int`, normally `component(...)` |
+| `serviceInstanceRelation(CLIENT \| SERVER, sourceService, sourceInstance, sourceLayer, destService, destInstance, destLayer, componentId)` | `newServiceInstanceRelation` with two layers | |
+
+Every constructor applies `NamingControl` to its names, because `MeterEntity` does. An entity held in a `def` has
+a compile-time scope type; reassigning it with a different constructor is a compile error, so `scope svc` always
+has one shape.
+
+The functions are the `MeterSystem` functions a span point can feed, named for what they do to the values of one
+minute:
+
+| `function` | `MeterSystem` function | Value type | Meaning per minute per entity |
+|---|---|---|---|
+| `cpm` | `sumPerMin` | `Long` | total of the values divided by the bucket's length in minutes, so hour and day rows read as a rate; `value 1` is calls per minute. `sumPerMin` computes `total / getDurationInMinute()`, which is what `CPMMetrics` computes for `core.oal`, so `cpm` is an alias and `sumPerMin` stays accepted |
+| `sum` | `sum` | `Long` | raw total of the values; at hour and day level the totals add rather than average |
+| `avg` | `avg` | `Long` | mean of the values; `value meta.latency` is mean latency |
+| `max`, `min`, `latest` | same | `Long` | |
+| `percent` | `percent`, new, see [section 5](#5-metrics-through-metersystem) | `Boolean` from `match` | `matches * 10000 / total`, the `core.oal` `percent(status == true)` scale; `match meta.statusCode != "ERROR"` is `service_sla` |
+| `apdex` | `apdex`, new, see [section 5](#5-metrics-through-metersystem) | `ApdexArgument` from `value` and `status` | the `core.oal` `apdex(name, status)`: thresholds from `service-apdex-threshold.yml` looked up by the entity's service name, satisfied under `T`, tolerated under `4T`, `(s * 10000 + t * 5000) / total` |
+| `sumLabeled`, `avgLabeled`, `maxLabeled`, `minLabeled`, `latestLabeled`, `sumPerMinLabeled` | same | `DataTable` keyed by the `labels` map | one series per label set, the shape MAL's labeled metrics have; `labels status: attr("http.response.status_code", "http.status_code")` splits a count by status code |
+| `histogram` | `sumHistogram` | `BucketedValues` | the observation counted in the bucket it falls into; buckets add across spans |
+| `percentile` | `sumHistogramPercentile` | `PercentileArgument` | the same buckets, reduced to the `ranks` at query time. `core.oal`'s `percentile2(10)` buckets by a fixed width instead; explicit buckets are coarser in the tail and cheaper to store |
+
+With `cpm`, `percent` and `apdex` a TAL metric named like an agent metric holds the same number in the same unit, so
+an alarm rule or a dashboard widget written for `service_sla` ports to `otlp_service_sla` by renaming the
+metric.
+
+`histogram` and `percentile` place the observation in the first bucket whose bound is not below the value and
+count `1` there; a value above the last bound lands in the last bucket, so the last bound is a finite overflow
+sentinel, the convention `IOSMetricKitSpanListener` follows. Percentiles use the summing function because counts
+from different spans add; the averaging variant MAL defaults to gives the same percentiles for one span per
+delivery and different ones for several, and there is no reason to prefer it here.
+
+The generated code for a block is the sequence `Analyzer` runs for one MAL entity, without the family in between:
+
+```java
+MeterEntity entity = MeterEntity.newService(h.toStr(...), h.layer(...)); // or the def variable
+h.traffic(entity); // once per distinct entity per execution
+AcceptableValue<Long> v = h.meterSystem().buildMetrics("otlp_service_cpm", Long.class);
+v.accept(entity, h.toLong(1));
+h.send(v, h.ctx().meta().getTimestamp()); // minute bucket, doStreamingCalculation
+```
+
+A `layer` expression that resolves to an unknown name at runtime skips the block, with one warning per name rather
+than per span; `Layer.nameOf` is not used for it because it answers `UNDEFINED` for an unknown name, and `UNDEFINED`
+is a layer a rule may name, for the `User` end of a relation. A `value` that does not parse as a number skips the
+block the same way. Both are visible in a debug session.
+
+#### 3.5 Output records: `outputType`
+
+A rule that declares `outputType` builds one record per span and writes it in `sink {}`. The mechanism is LAL's:
+the generated `execute()` creates the output object before the extractor runs, every extractor statement whose name
+is not a keyword becomes a setter call on it, validated at compile time, and the sink stage runs the builder's
+lifecycle. Two output paths exist, as in LAL.
+
+**Builder path.** `outputType` names a `TALOutputBuilder`, by its `name()` or its FQCN:
+
+```java
+public interface TALOutputBuilder {
+ String name(); // `SlowSQL`
+ default void bindInput(SpanMetadata meta, Object input) { } // called right after creation
+ void init(SpanMetadata meta, Object input, ModuleManager moduleManager); // sink stage: NamingControl, standard fields
+ void complete(SourceReceiver sourceReceiver); // validate and dispatch the source(s)
+ String outputToJson(); // the debugger's output payload
+}
+```
+
+It is `LALOutputBuilder` with `SpanMetadata` in place of `LogMetadata`, in `server-core` next to it, discovered by
+`ServiceLoader` into the same kind of name registry. A builder that serves both DSLs implements both interfaces;
+`DatabaseSlowStatementBuilder`, today's `SlowSQL`, gains the second one and reads `serviceName`, `layer`,
+`timestamp` and `traceId` from `meta` in its span-side `init`, which is the only span-specific code the record
+needs. The standard fields, `service`, `instance`, `endpoint`, `layer`, are taken from `meta` at `init`, so the
+`service` statement in the extractor names the record's service by overwriting `meta.service`, exactly as a LAL
+slow-SQL rule does with `service parsed.service`. The available output fields are the builder's setters:
+`id`, `statement` and `latency` for `SlowSQL`.
+
+**Source path.** `outputType` names a `Source` subclass by FQCN. The sink sets `timeBucket` from `meta.timestamp`
+and calls `SourceReceiver.receive`; the extractor's field statements are the subclass's setters. This is the escape
+hatch to `core.oal`: a builder that fills `ServiceRelation` or `DatabaseAccess` from a span would give an OTLP
+service the agent metrics, which is the source-mapping proposal expressed in TAL. The shipped rules do not use it,
+and this proposal does not recommend it, because mixing `core.oal` entities with `otlp_*` ones for the same
+fleet doubles the identity problem [section 6](#6-the-otlp_service-layer) exists to avoid. It is documented so that
+a deployment that wants parity for one record type can have it without a Java change.
+
+The shipped slow-statement rule, part of `tal/otlp-default.yaml`:
+
+```yaml
+ - name: otlp-slow-sql
+ layer: auto
+ inputType: otlp
+ outputType: SlowSQL
+ dsl: |
+ filter {
+ if (meta.kind != "CLIENT" || !hasAttr("db.query.text", "db.statement")) {
+ abort {}
+ }
+ // Milliseconds. The agent path keys this by database type (slowDBAccessThreshold); edit per deployment.
+ if (meta.latency < 200) {
+ abort {}
+ }
+ extractor {
+ layer "OTLP_VIRTUAL_DATABASE"
+ // The record belongs to the database service, named as the topology names it.
+ def peer = attr("service.peer.name", "peer.service")
+ if (!peer) {
+ // The port is optional; without it the bare address is the name, not a name ending in a colon.
+ def addr = attr("server.address", "net.peer.name")
+ def port = attr("server.port", "net.peer.port")
+ def peer = addr
+ if (port) {
+ def peer = addr + ":" + port
+ }
+ }
+ service peer
+ id meta.spanId
+ statement attr("db.query.text", "db.statement")
+ latency meta.latency
+ }
+ sink {}
+ persist {
+ enforcer {} // keep the span behind every slow statement, past this rule's samplers and the receiver's head sampling
+ }
+ }
+```
+
+`DatabaseSlowStatement.traceId` carries the span's trace id in hex, and the record shows on the virtual database's
+slow-statement panel because `databaseServiceId` is built from the same name and layer the relation in
+[section 7](#7-shipped-rule) gives the peer. The trace link resolves where the service's trace tab does, the same UI
+dependency the storage proposal records. `CacheSlowAccess` has no builder today; adding one is the same shape and
+a follow-up.
+
+Ordering inside one rule: the extractor runs first and may set metrics, fields and tags in any order; `sink {}`
+then decides the record; `persist {}` then decides the span. A rule that aborted anywhere writes nothing and votes
+nothing.
+
+#### 3.6 Grammar
+
+`TALLexer.g4` and `TALParser.g4` live in `trace-analyzer/src/main/antlr4`, derived from the LAL grammars:
+`PARSED`, `LOG`, `PROCESS_REGISTRY`, the parser-block rules and the four identifier statements are removed; `SPAN`,
+`META`, `SCOPE`, `FUNCTION`, `BUCKETS`, `RANKS`, `MATCH`, `STATUS`, `CLIENT`, `SERVER`, `PERSIST`, `ALIAS` and a numeric list literal
+`L_BRACKET NUMBER (COMMA NUMBER)* R_BRACKET` are added; `outputFieldStatement` stays as LAL defines it;
+`persistBlock` mirrors `sinkBlock`; `abortBlock` joins `extractorStatement`, `sinkStatement` and
+`persistStatement`; `SEMI` becomes an optional statement separator. The entity constructors are ordinary
+`functionInvocation`s the compiler recognizes by name. Keywords stay usable as identifiers in label names and
+getter chains through `anyIdentifier`, so `labels service: meta.service` parses.
+
+### 4. Compiler and runtime
+
+The pipeline is LAL's: ANTLR4 parses the DSL into an immutable model, a Javassist generator emits one class per
+rule implementing `TalExpression.execute(FilterSpec, ExecutionContext)`, extractor and sink become private methods
+guarded by the abort flag, every spec method takes the context explicitly, no `ThreadLocal`.
+
+The value and condition codegen a TAL rule needs is the shape `LALValueCodegen` and `LALDefCodegen` already have:
+getter chains resolved by reflection at compile time, `def` with type inference, casts, arithmetic with JLS-style
+numeric promotion, safe navigation, comparisons and the built-in functions. **TAL carries its own copy**, in
+`trace-analyzer`'s `compiler` package: `TALValueCodegen`, `TALDefCodegen`, `TALGenCtx`, `TALCodegenHelper`,
+`ExprType` and the model interfaces the engine reads a parsed expression through. `log-analyzer` is not touched by
+this proposal and not depended on.
+
+Sharing one module between the two DSLs was the earlier plan and was rejected: it would put every future TAL change
+on log analysis's path, where a regression in span metrics becomes a regression in log parsing. The isolation is
+worth more than the duplication, and the duplication is the cost this design accepts — roughly nineteen hundred
+lines that will drift, so a fix in one engine has to be checked against the other. `TALValueCodegen` names
+`LALValueCodegen` as its sibling in a header comment for that reason.
+
+What the copy does not duplicate is TAL's own vocabulary, which stays behind one seam, `TALRootResolver`: the
+`span` and `meta` roots, `attr()` and the rest of [section 3.2](#32-what-a-rule-can-read), and the entity
+constructors. The expression engine calls the resolver and knows nothing about spans. Block structure, spec classes
+and the generated-class scaffolding are TAL's own throughout.
+
+Compiling a rule resolves its input and output types first. Each `inputType` entry is matched against the
+registered `TALSourceTypeProvider` aliases, then tried as a FQCN that a provider declares; an entry that is
+neither is a compile error, because the functions need the provider's attribute reader. The `span` root is typed
+to the single declared input, and getter and method chains are resolved on it by reflection at compile time.
+`outputType` is matched against the `TALOutputBuilder` name registry, then tried as a FQCN that is a
+`TALOutputBuilder` or a `Source` subclass; the output object is created at the top of `execute()`, and every
+output-field statement is checked against a setter on it, as LAL does. There is no per-layer default output type:
+`outputType` is per rule or absent.
+
+Compiling a rule registers its metrics. The generator collects every `metrics {}` block, including those inside
+`if` branches, into a set of `(fullName, function, scopeType)` declarations and calls
+`MeterSystem.create(fullName, function, scopeType)` for each before the class is loaded. Two blocks declaring the
+same name with the same shape, in one rule or across rules, share one metric, which is how `if` / `else` branches
+feed one series; the same name with a different function or scope type is a compile error naming both rules. On
+the boot path `create` is create-if-absent, as for MAL; on the runtime-rule path the per-file `ClassPool`,
+`ClassLoader` and `StorageManipulationOpt` overload is used, `withSchemaChange()` on the node that applies and
+`withoutSchemaChange()` on peers, exactly as `MalFileApplier` does today.
+
+Generated classes are named `org.apache.skywalking.oap.trace.analyzer.v2.compiler.rt.{yaml}_L{line}_{rule}` with a
+`LocalVariableTable` and a `SourceFile` of `tal/<file>.yaml`, through the shared `DslClassNaming`,
+`DslSourceRef` and `DslGeneratedFileWriter`. `SW_DYNAMIC_CLASS_ENGINE_DEBUG=true` dumps them, with the Java
+source Javassist compiled, to `{skywalking}/tal-rt/`.
+
+Compile-time validation fails OAP startup, or rejects the runtime-rule push, on: a syntax error, an `inputType`
+entry no provider claims, a `span.*` root in a rule with more than one input, a `span.*` or `meta.*` chain with no
+matching getter, a function with the wrong arity, a `layer` literal `Layer.nameOf` does not know, an `outputType`
+that is neither a registered builder name nor a `TALOutputBuilder` or `Source` class, an output-field statement
+with no matching setter, an output-field statement or a `sink {}` in a rule without `outputType`, a `metrics {}`
+block missing `name`, `scope` or `function`, `value` missing from any block but `percent` or present on one,
+`match` missing from `percent` or present elsewhere, `status` missing from `apdex` or present elsewhere, `labels`
+without a labeled function or a labeled function without `labels`, `buckets` missing for `histogram` and
+`percentile` or present for anything else, a bucket list
+that is empty or not ascending, a metric name declared with two shapes, an extractor `layer` missing from a
+`layer: auto` rule that never aborts, and a duplicate rule name within a layer or within the auto set.
+
+Per span, the cost is: one `SpanMetadata`, one attribute index on first use, and the compiled rules of one layer.
+There is no reflection, no map-of-maps binding and no closure allocation on the hot path; a `metrics {}` block
+allocates one `AcceptableValue` and, for histograms, one `BucketedValues`. Entity traffic is generated once per
+distinct entity per execution, not once per block.
+
+The optional `dedupWindow` keeps a bounded seen-set of `(traceId, spanId)` in front of the rules, `SeenSpans` in
+`TraceAnalyzerServiceImpl`, so an exporter that retries a batch after a transport timeout does not count a request
+twice; a retried span runs no rule, joins no pair and casts no vote. It is off by default because OTLP logs feeding
+LAL have the same exposure and no such set today; a deployment that wants exact counts turns it on, knowing the set
+is per OAP node and holds at most `dedupCapacity` entries.
+
+### 5. Metrics through `MeterSystem`
+
+Nothing new is needed to store or query a TAL metric. `MeterSystem.create` generates the metric class and installs
+its storage model at compile, `buildMetrics` and `doStreamingCalculation` carry each value into the same L1
+aggregation and minute, hour and day downsampling MAL metrics get, and the query side reads `otlp_*` as it
+reads every meter metric. Three core changes are required, all additive and all shared with MAL afterwards.
+
+**Entity traffic moves to core.** `Analyzer.generateTraffic` and its helpers `toService`,
+`serviceRelationTraffic`, `serviceRelationServerSide`, `serviceRelationClientSide`, `serviceInstanceRelationTraffic`
+and the process-relation pair are the only code that turns a `MeterEntity` into `ServiceTraffic`, `InstanceTraffic`,
+`EndpointTraffic`, `ServiceRelationClientSideMetrics` and `ServiceRelationServerSideMetrics`, the rows the service
+lists and `TopologyQueryService` read. They are private to `meter-analyzer`. They move to `server-core` as
+`EntityTrafficGenerator.generate(MeterEntity)` next to `MeterSystem`, `Analyzer` delegates to it, and TAL calls
+it. No behavior changes for MAL; the MAL `.data.yaml` tests are the guard.
+
+**The component catalog answers a case-insensitive lookup.** `IComponentLibraryCatalogService` gains
+`getComponentIdIgnoreCase(name)`, exact match first and then the catalog names folded to lower case, because the
+semantic conventions spell systems in lower case, `grpc`, `postgresql`, `kafka`, while `component-libraries.yml`
+spells them `GRPC`, `PostgreSQL`, `Kafka`; `getComponentId` is untouched. The profile exporter's mock catalog
+implements it too. `component-libraries.yml` gains `Connect_RPC` (id 181), which folds to the conventions'
+`connect_rpc`, the system flagd's callers report in the demo; the other `rpc.system` values the catalog lacks,
+`java_rmi`, `dotnet_wcf`, `onc_rpc`, and the `apache_dubbo` spelling of `Dubbo`, still resolve to `Unknown`.
+
+**Relations get a layer per side.** `MeterEntity.newServiceRelation` takes one `Layer` for both ends and `id()`
+builds both service ids with that layer's `normal` flag. A call from an OTel service to PostgreSQL has a normal
+source and a conjectured destination, `OTLP_VIRTUAL_DATABASE`, and the layer of the destination is only known per span.
+`MeterEntity` gains `destLayer`, new factory overloads take `sourceLayer` and `destLayer`, `sourceServiceId()` and
+`destServiceId()` use their own side's `normal` flag, and for entities built with two layers
+`EntityTrafficGenerator` emits `ServiceTraffic` for both ends in their own layers, so a virtual database appears in
+the `OTLP_VIRTUAL_DATABASE` list the way the agent path's `ServiceMeta` puts it there. A two-layer relation takes
+each layer's own `normal` flag, `UNDEFINED` included, the way the agent path's `ServiceRelation` source builds the
+same ids, and an `UNDEFINED` end gets no `ServiceTraffic` row: that is what makes `User` in
+[section 6](#6-the-otlp_service-layer) a node without a service list entry. The single-layer factories and
+their traffic behavior are untouched; MAL does not use the new overloads unless a later change gives it a syntax
+for them.
+
+**Two functions ported from OAL, one alias.** The `core.oal` metrics the dashboards and alarm rules were built on
+use four functions a span point can feed: `cpm`, `percent`, `apdex` and `longAvg`. `MeterSystem` has `avg` for
+the last, and `sumPerMin` is `cpm` under another name: both compute `total / getDurationInMinute()`, so TAL spells
+it `cpm` and maps it to `sumPerMin`. The other two do not exist on the `MeterSystem` side and are added as
+`@MeterFunction` classes in `core.analysis.meter.function`, ported from their OAL counterparts:
+
+| Class | Accepts | Fields | `calculate()` |
+|---|---|---|---|
+| `PercentFunction`, `percent` | `Boolean` | `total`, `match`, `percentage` | `match * 10000 / total`, as `PercentMetrics` |
+| `ApdexFunction`, `apdex` | `ApdexArgument{int latency, String serviceName, boolean status}` | `total_num`, `s_num`, `t_num`, `int_value` | `(s_num * 10000 + t_num * 10000 / 2) / total_num`, as `ApdexMetrics`; `t = DICT.lookup(serviceName)`, satisfied when `latency <= t`, tolerated when `latency <= 4t`, unsuccessful spans count only in `total_num` |
+
+Both follow the `AvgFunction` shape: `entityId`, `serviceId`, `combine(Metrics)`, `toHour()`, `toDay()`, a
+`StorageBuilder`, `createNew()`. `ApdexFunction` reads the same `ConfigurationDictionary` `ApdexMetrics` reads:
+`CoreModuleProvider` already builds `ApdexThresholdConfig` from `service-apdex-threshold.yml` with its dynamic
+configuration watcher and hands it to `ApdexMetrics.setDICT`; it hands the same instance to `ApdexFunction`. The
+generated TAL code fills `ApdexArgument.serviceName` from `MeterEntity.getServiceName()`, so a service, instance
+or endpoint scope gets the service's threshold, as `service_apdex = from(Service.latency).apdex(name, status)`
+does. Both classes register in `MeterSystem.functionRegister` by annotation scan like every other function, so MAL
+can reach them once it has a syntax for a boolean or an apdex argument; that is not part of this proposal.
+
+**The service catalogs stay separate.** Nothing above touches the trace side: TAL's entity traffic and the
+service-name catalogs of [the native OTLP trace storage](SWIP-otlp-native-trace.md) are different rows answering
+different questions. `otlp_service_traffic`, `otlp_service_span_traffic` and `otlp_service_relation_traffic` are
+TraceQL tag-value dictionaries, keyed by the raw service name and read only by the `resource.service.name`, `name`
+and `resource.remote.service` value lists; they carry neither a layer nor a service id. A metric row is found by its
+`entity_id`, which the query side builds as `IDManager.ServiceID.buildId(serviceName, normal)`, and the service list
+a dashboard is scoped by reads `ServiceTraffic.layer`, so the metrics path needs its own `ServiceTraffic` row. The
+two are filled at different points as well: `OTLPSpanForward.send` writes its catalogs after head sampling and the
+rate limit, so they hold only the spans that were stored, while TAL runs ahead of the forward on every span, and
+folding one into the other would tie the service list and the metric denominators to `otlpTraceSampleRate`. Both
+names pass through `NamingControl.formatServiceName`, so a service appears under the same spelling in both and the
+jump from an `OTLP_SERVICE` dashboard to its traces resolves.
+
+### 6. The `OTLP_SERVICE` layer
+
+A new normal layer, `Layer.OTLP_SERVICE = register("OTLP_SERVICE", 52, true)`, "a service whose spans arrived over
+OTLP and were analyzed by TAL", is where the shipped rule puts them. `GENERAL` is not an option: its dashboards read
+`service_cpm`, `service_sla` and the other `core.oal` metrics, which this design does not produce, and a `GENERAL`
+service list with empty columns is worse than a separate list.
+
+Three more layers carry the conjectured peers: `OTLP_VIRTUAL_DATABASE = register(..., 53, false)`,
+`OTLP_VIRTUAL_CACHE` (54) and `OTLP_VIRTUAL_MQ` (55). They are separate from the agent path's `VIRTUAL_DATABASE`
+and friends because a peer's metrics come from a different engine and carry different names, so mixing the two in
+one list gives half its rows empty columns. `VIRTUAL_GENAI` is the precedent for a conjectured layer filled from
+OTLP spans.
+
+A peer is not just a node in the topology: the rule gives it `otlp_database_access_cpm`, `_resp_time` and `_sla`,
+and the cache and MQ counterparts, named after the agent metrics of the same shape so a dashboard widget written
+for `database_access_cpm` ports by renaming. Without them the layer's service list would have nothing to show.
+
+All three are **non-normal**, and that is a correctness requirement rather than a style: the layer is only ever a
+property of the `ServiceTraffic` row — `ServiceTraffic.id0()` is name plus layer, while a metric's `entityId` is name plus the
+`normal` flag — so the layer a peer is listed under never splits its metrics or its topology edges. A peer layer
+must therefore stay non-normal; registering one as normal would change the peer's service id and stop it merging
+with the agent-observed node.
+
+A service id is its name plus the `normal` flag, not the layer, so a service that reports both agent segments and
+OTLP spans is one entity listed under both layers, each with its own dashboards, which is how a service today can
+be both `GENERAL` and `K8S_SERVICE`. A process running an agent and an SDK at once is counted in both places; that
+is documented, not prevented. Rules that want another layer pass it to the entity constructors; a fleet that
+stamps `service.layer` on its resources writes its rules under that layer.
+
+**Address-named peers and `NetworkAddressAliasSetup`.** A CLIENT span names its peer by what it dialed,
+`server.address:server.port`, and the callee names itself by `service.name`; nothing in OTLP ties the two, since
+W3C `traceparent` carries no address. A fleet that does not set `peer.service` therefore gets
+`productcatalogservice:3550` beside `productcatalogservice` in the `OTLP_SERVICE` list and in the topology, which is
+what OpenObserve's service graph shows for the same demo, `oteldemo.CartService` beside `cart`. The agent path
+solves this with the alias the `sw8` header lets the callee register: `NetworkAddressAliasMappingListener` emits a
+`NetworkAddressAliasSetup` for the address the caller used, the row lands in `network_address_alias`,
+`CacheUpdateTimer` reloads it into `NetworkAddressAliasCache` every 10 seconds, and both `RPCAnalysisListener` at
+analysis time and `ServiceTopologyBuilder` at query time substitute the represented service for the address. TAL
+reuses the row, the table, the timer and both readers; only the source of the address differs. A SERVER span's
+`server.address` and `server.port` are the `Host` or `:authority` the caller sent, which the HTTP semantic
+conventions define as the same value on both sides, so the shipped rule's `alias <address>` statement registers
+that address for `meta.service`, with the `normal` flag of `meta.layer` so the id is the one
+`service(meta.service, meta.layer)` gave the SERVER span's own metrics, and `resolveAlias(peer)` on the CLIENT
+branch returns the represented service's name when the cache has the address, or the address unchanged. The rows
+travel through storage and the timer, so the first calls to a freshly seen address are still address-named, and
+the query-time fold covers those.
+
+Two guards keep the alias honest, both backed by `KnownServices`, a bounded per-OAP registry of the service
+names seen on analyzed spans that `TraceAnalyzerServiceImpl` feeds before any rule runs. First, `alias` skips an
+address whose host names another service: an Envoy that keeps the `Host` header hands `frontend-proxy:8080` to
+the `frontend` behind it, whose SERVER span would otherwise register the proxy's address as its own and pull
+every edge to the proxy onto itself, which is what the demo run showed before the guard. Second, `resolveAlias`
+asks the registry before the cache: a host, or its first DNS label, that is a known service's name resolves to
+that service, so `product-catalog:3550` lands on `product-catalog` although its Go server reports its IP, and a
+row a proxy did manage to poison cannot redirect the edge. That is OpenObserve's first-label rule and its
+self-key override in one place. The registry is per OAP node; a node that has not yet seen a service's spans
+applies the guard late, not wrongly, since the fallback is the address-named node. Both `alias` and the pairing
+below write their rows through one `AliasRegistrar`, so the guard covers a learned row as well. Coverage of the
+alias row itself follows the SDK: HTTP servers fill `server.address` from the request
+headers; gRPC servers only when the instrumentation does, and the demo's Go server does not, so a callee that
+reports no address is only ever reached by name. The rest is covered by the pairing.
+
+**Pairing a call's two spans.** A peer that neither the registry nor the cache can name, a callee dialed by IP,
+or one whose SDK reports its own address under another spelling or not at all, is resolved from the trace context:
+the SERVER span's `parentSpanId` is the CLIENT span's id, which needs no attribute convention on either side.
+Each half of a call is a `PairingFact`, a `StreamData` of the trace id, span id, parent span id, service,
+`normal` flag, instance, timestamp, and for the CLIENT side the address it dialed. `SpanPairing`, a module
+service, sends every fact to the node that owns the trace through the core's `RemoteSenderService` with
+`Selector.HashCode` on the trace id, the channel and the selector `MetricsRemoteWorker` uses to bring every value
+of one metric to one node; `PairingWorker`, registered under `TAL_SPAN_PAIRING` with the core's worker registry,
+is the receiving end. The two spans arrive in separate batches, in either order, and at different nodes, and both
+facts still meet at the owner. The owner keeps two bounded buffers of 60 seconds: callers whose peer `resolveAlias`
+could not name, keyed by their own span id, and callees, keyed by their parent span id, which
+`TraceAnalyzerServiceImpl` sends for every SERVER span with a parent before any rule runs; a CONSUMER span is left
+out, because its parent is the PRODUCER span and pairing the two would register the broker's address as an alias of
+the consumer, which the Intro-to-MLTP run did before the exclusion. A match
+writes `NetworkAddressAliasSetup(peer -> callee)` and the owner remembers the answer for ten minutes, so its own
+next callers of that address resolve before the row has come back through storage; every other node resolves it
+through its cache once the timer has loaded the row. When the CLIENT side is analyzed on the owner and the SERVER
+span is already there, `resolveAlias` returns the callee at once and that very edge lands on it; otherwise the
+edge is address-named this once. A single node, and a cluster whose membership has not loaded yet, pairs locally.
+`pairingSamplePercent`, 25 by default, limits a cluster's channel traffic to a share of traces chosen by a second
+hash of the trace id, separate from the one that picks the owner so that the sampled share is spread over every node
+rather than over the residues the owner selection shares with it, and which both halves compute alike; an address only has to be learned once, so a busy edge still learns within
+its first few calls, and a single node ignores the rate. Root spans have nothing to pair with and are not kept.
+This is the join Tempo's service-graph processor and OpenObserve's pairing learner run over stored spans, done at
+analysis time instead and without their tables: one row per address is all the alias mechanism needs. The
+buffers cost at most 200,000 entries each; a call whose SERVER span never arrives, an uninstrumented callee or a
+dropped trace context, leaves its caller to expire and its edge address-named, which is the honest answer. While
+the cluster membership changes, the hash re-targets and a pair in flight can split, which delays learning that
+address by one more call, the same window the metrics channel has.
+
+**The `User` node.** A root SERVER span was called from outside the fleet. The shipped rule draws that as
+`serviceRelation(SERVER, "User", "UNDEFINED", meta.service, meta.layer, comp)` with one
+`service_relation_server_cpm` value, the edge `RPCAnalysisListener` draws for an entry span without a reference.
+`User`'s id is built from `Layer.UNDEFINED`'s own flag, non-normal, which is the id `ServiceTopologyBuilder`
+recognizes and labels, and `EntityTrafficGenerator` writes no `ServiceTraffic` for an `UNDEFINED` end, so `User` is
+a node of the topology and not a service in any list, as on the agent path.
+
+### 7. Shipped rule
+
+`tal/otlp-default.yaml` is the whole feature: the semantic-convention knowledge, with the current attribute names
+first and the deprecated spellings older SDKs still emit as fallbacks, and the metric set the `OTLP_SERVICE`
+dashboards use. It holds two rules, `otlp-service` below and `otlp-slow-sql` from
+[section 3.5](#35-output-records-outputtype). Both declare `inputType: otlp`; a deployment that wants the same
+analysis for Zipkin-reported spans would add `zipkin` to that line once the reserved Zipkin provider of
+[section 2.2](#22-zipkin--reserved-not-in-scope) exists. It is written to be edited.
+
+```yaml
+metricPrefix: otlp
+
+rules:
+ - name: otlp-service
+ # `auto` means: see the spans whose resource carries no `service.layer`, and name the layer yourself.
+ layer: auto
+ inputType: otlp
+ dsl: |
+ filter {
+ // Spans with a dedicated analyzer: MetricKit payloads and GenAI calls are handled by their SpanListeners.
+ if (meta.scopeName == "MetricKit" || hasAttr("gen_ai.provider.name", "gen_ai.system")) {
+ abort {}
+ }
+ // A messaging poll is transport bookkeeping, not a request anyone can be measured on. The OpenTelemetry
+ // Java agent reports a blocking JMS receive as a CONSUMER span as long as the wait, so the kind alone cannot
+ // tell a poll from a handled message; the operation can.
+ if ((meta.kind == "CLIENT" || meta.kind == "CONSUMER")
+ && attr("messaging.operation.type", "messaging.operation") == "receive") {
+ abort {}
+ }
+
+ extractor {
+ layer "OTLP_SERVICE"
+
+ // Inbound: SERVER and CONSUMER spans are requests this service answered.
+ if (meta.kind == "SERVER" || meta.kind == "CONSUMER") {
+ // `{method} {route}` when the framework reports a route; otherwise the span name stays the endpoint.
+ if (hasAttr("http.route")) {
+ endpoint attr("http.request.method", "http.method") + " " + attr("http.route")
+ }
+ def svc = service(meta.service, meta.layer)
+ metrics { name "service_cpm"; scope svc; function cpm; value 1 }
+ metrics { name "service_resp_time"; scope svc; function avg; value meta.latency }
+ metrics { name "service_sla"; scope svc; function percent; match meta.statusCode != "ERROR" }
+ metrics { name "service_apdex"; scope svc; function apdex; value meta.latency; status meta.statusCode != "ERROR" }
+ metrics { name "service_percentile"; scope svc; function percentile; value meta.latency
+ buckets [10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] }
+
+ def ep = endpoint(meta.service, meta.endpoint, meta.layer)
+ metrics { name "endpoint_cpm"; scope ep; function cpm; value 1 }
+ metrics { name "endpoint_resp_time"; scope ep; function avg; value meta.latency }
+ metrics { name "endpoint_sla"; scope ep; function percent; match meta.statusCode != "ERROR" }
+ metrics { name "endpoint_percentile"; scope ep; function percentile; value meta.latency
+ buckets [10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] }
+
+ if (meta.serviceInstance) {
+ def inst = instance(meta.service, meta.serviceInstance, meta.layer)
+ metrics { name "instance_cpm"; scope inst; function cpm; value 1 }
+ metrics { name "instance_resp_time"; scope inst; function avg; value meta.latency }
+ metrics { name "instance_sla"; scope inst; function percent; match meta.statusCode != "ERROR" }
+ }
+ }
+
+ // A consumer was called by its broker.
+ if (meta.kind == "CONSUMER" && hasAttr("messaging.system")) {
+ def broker = attr("server.address", "net.peer.name")
+ if (broker && hasAttr("server.port", "net.peer.port")) {
+ def broker = broker + ":" + attr("server.port", "net.peer.port")
+ }
+ // A consumer that reports no broker address, as the JMS API gives its clients none, lands on the node
+ // named after the messaging system, the same one the producer side draws below, so one queue has one
+ // broker. The port alone would be a worse name than that.
+ if (!broker) {
+ def broker = attr("messaging.system")
+ }
+ def fromBroker = serviceRelation(SERVER, broker, "OTLP_VIRTUAL_MQ", meta.service, meta.layer,
+ component(attr("messaging.system")))
+ metrics { name "service_relation_server_cpm"; scope fromBroker; function cpm; value 1 }
+ }
+
+ // Inbound, SERVER only: what this service was dialed as, and who dialed it.
+ if (meta.kind == "SERVER") {
+ def comp = component("http")
+ if (hasAttr("rpc.system.name", "rpc.system")) {
+ def comp = component(attr("rpc.system.name", "rpc.system"))
+ }
+ // The address a SERVER span reports is the `Host` / `:authority` its caller used, so registering it as
+ // an alias lets a CLIENT span's resolveAlias(peer) below land the edge on this service instead of on a
+ // second node named by the address. A callee that reports no address is only ever reached by name.
+ // An address whose host is another service's name, a proxy's `Host` passed through, is not registered.
+ if (hasAttr("server.address", "net.host.name")) {
+ def addr = attr("server.address", "net.host.name")
+ def port = attr("server.port", "net.host.port")
+ def dialed = addr
+ if (port) {
+ def dialed = addr + ":" + port
+ }
+ alias dialed
+ }
+ // A root span was called from outside the fleet, which the agent path draws as `User`.
+ if (meta.root) {
+ def fromUser = serviceRelation(SERVER, "User", "UNDEFINED", meta.service, meta.layer, comp)
+ metrics { name "service_relation_server_cpm"; scope fromUser; function cpm; value 1 }
+ }
+ }
+
+ // Outbound: CLIENT and PRODUCER spans are calls this service made. The peer decides the edge.
+ if (meta.kind == "CLIENT" || meta.kind == "PRODUCER") {
+ // The peer is named first, because the metrics below are scoped to it. `peer.service` is the
+ // deprecated spelling of `service.peer.name`; SDKs on either side of that rename still emit one of them.
+ def peer = attr("service.peer.name", "peer.service")
+ if (!peer && hasAttr("server.address", "net.peer.name")) {
+ // The port is optional. Without it the node is the bare address, the spelling the callee's own
+ // service name takes, rather than a third one ending in a colon.
+ def addr = attr("server.address", "net.peer.name")
+ def port = attr("server.port", "net.peer.port")
+ def peer = addr
+ if (port) {
+ def peer = addr + ":" + port
+ }
+ }
+ // Envoy, and other instrumentations of OpenTracing descent, name the peer as `peer.address`, host and
+ // port in one string, and report no server.address at all.
+ if (!peer && hasAttr("peer.address")) {
+ def peer = attr("peer.address")
+ }
+ // A client that names its target only as a URL, the Python requests instrumentation among them, still
+ // carries the host and port there.
+ if (!peer && hasAttr("url.full", "http.url")) {
+ def peer = urlHost(attr("url.full", "http.url"))
+ }
+ // A peer whose host names a service, or that some SERVER span registered through `alias`, resolves to
+ // that service, so the edge lands on the callee's own node instead of one named by the address.
+ def peer = resolveAlias(peer)
+ // A peer reached without an address, an embedded database or a broker the JMS API hides, is named
+ // after what the span does know: the database system and its namespace, or the messaging system alone,
+ // with the destination carried as an endpoint of that node below. Neither is an address, so the alias
+ // cache and the pairing have nothing to fold and are not asked. A client span that knows none of these
+ // still names no peer and draws no edge.
+ if (!peer && hasAttr("db.system.name", "db.system")) {
+ def peer = attr("db.system.name", "db.system")
+ if (hasAttr("db.namespace", "db.name")) {
+ def peer = peer + "/" + attr("db.namespace", "db.name")
+ }
+ }
+ if (!peer && hasAttr("messaging.system")) {
+ def peer = attr("messaging.system")
+ }
+ if (peer) {
+ def peerLayer = "OTLP_SERVICE"
+ def comp = component("http")
+ if (hasAttr("rpc.system.name", "rpc.system")) {
+ def comp = component(attr("rpc.system.name", "rpc.system"))
+ }
+ if (hasAttr("db.system.name", "db.system")) {
+ def system = attr("db.system.name", "db.system")
+ def peerLayer = "OTLP_VIRTUAL_DATABASE"
+ if (system == "redis" || system == "valkey" || system == "memcached") {
+ def peerLayer = "OTLP_VIRTUAL_CACHE"
+ }
+ def comp = component(system)
+ }
+ if (hasAttr("messaging.system")) {
+ def peerLayer = "OTLP_VIRTUAL_MQ"
+ def comp = component(attr("messaging.system"))
+ }
+
+ // A conjectured peer gets metrics of its own, not just a node in the topology, so its layer's service
+ // list has columns to fill. Named after the agent metrics of the same shape, so a widget written for
+ // `database_access_cpm` ports by renaming.
+ def peerSvc = service(peer, peerLayer)
+ if (peerLayer == "OTLP_VIRTUAL_DATABASE") {
+ metrics { name "database_access_cpm"; scope peerSvc; function cpm; value 1 }
+ metrics { name "database_access_resp_time"; scope peerSvc; function avg; value meta.latency }
+ metrics { name "database_access_sla"; scope peerSvc; function percent
+ match meta.statusCode != "ERROR" }
+ }
+ if (peerLayer == "OTLP_VIRTUAL_CACHE") {
+ metrics { name "cache_access_cpm"; scope peerSvc; function cpm; value 1 }
+ metrics { name "cache_access_resp_time"; scope peerSvc; function avg; value meta.latency }
+ metrics { name "cache_access_sla"; scope peerSvc; function percent
+ match meta.statusCode != "ERROR" }
+ }
+ if (peerLayer == "OTLP_VIRTUAL_MQ") {
+ metrics { name "mq_access_cpm"; scope peerSvc; function cpm; value 1 }
+ metrics { name "mq_access_resp_time"; scope peerSvc; function avg; value meta.latency }
+ metrics { name "mq_access_sla"; scope peerSvc; function percent
+ match meta.statusCode != "ERROR" }
+ // The queue or topic is an endpoint of its broker, so the virtual layer's list stays one row per
+ // broker while the destinations are still there to rank.
+ if (hasAttr("messaging.destination.name", "messaging.destination")) {
+ def dest = endpoint(peer, attr("messaging.destination.name", "messaging.destination"), peerLayer)
+ metrics { name "mq_destination_cpm"; scope dest; function cpm; value 1 }
+ metrics { name "mq_destination_resp_time"; scope dest; function avg; value meta.latency }
+ metrics { name "mq_destination_sla"; scope dest; function percent
+ match meta.statusCode != "ERROR" }
+ }
+ }
+
+ def edge = serviceRelation(CLIENT, meta.service, meta.layer, peer, peerLayer, comp)
+ metrics { name "service_relation_client_cpm"; scope edge; function cpm; value 1 }
+ metrics { name "service_relation_client_resp_time"; scope edge; function avg; value meta.latency }
+ metrics { name "service_relation_client_sla"; scope edge; function percent
+ match meta.statusCode != "ERROR" }
+ }
+ }
+ }
+ // No outputType and no persist block: this rule writes no record and takes no part in the span's persistence.
+ }
+
+ - name: otlp-slow-sql
+ layer: auto
+ inputType: otlp
+ outputType: SlowSQL
+ dsl: |
+ filter {
+ if (meta.kind != "CLIENT" || !hasAttr("db.query.text", "db.statement")) {
+ abort {}
+ }
+ // Milliseconds. The agent path keys this by database type (slowDBAccessThreshold); edit per deployment.
+ if (meta.latency < 200) {
+ abort {}
+ }
+ extractor {
+ layer "VIRTUAL_DATABASE"
+ // The record belongs to the database service, named as the topology names it.
+ def peer = attr("service.peer.name", "peer.service")
+ if (!peer) {
+ // The port is optional; without it the bare address is the name, not a name ending in a colon.
+ def addr = attr("server.address", "net.peer.name")
+ def port = attr("server.port", "net.peer.port")
+ def peer = addr
+ if (port) {
+ def peer = addr + ":" + port
+ }
+ }
+ // A statement with no database to file it under would land on a service named `_blank`, where no
+ // panel reads it.
+ if (!peer) {
+ abort {}
+ }
+ service peer
+ id meta.spanId
+ statement attr("db.query.text", "db.statement")
+ latency meta.latency
+ }
+ sink {}
+ persist {
+ enforcer {} // keep the span behind every slow statement, past this rule's samplers and the receiver's head sampling
+ }
+ }
+```
+
+Compiling the `otlp-service` rule registers sixteen metrics: `otlp_service_cpm`, `_service_resp_time`,
+`_service_sla`, `_service_apdex`, `_service_percentile`, the four endpoint counterparts, the three instance
+counterparts, `_service_relation_client_cpm`, `_resp_time`, `_sla`, and `_service_relation_server_cpm`. Each is
+the function `core.oal` uses for the agent metric of the same name, `cpm`, `avg`, `percent`, `apdex`, so the
+values and units match: `otlp_service_sla` is in ten-thousandths like `service_sla`, and
+`otlp_service_cpm` reads as a rate at hour and day level like `service_cpm`. The `otlp_` prefix keeps
+the two sets apart in storage and in queries.
+
+After this one file, an OpenTelemetry SDK service appears under `OTLP_SERVICE` with load, latency, success rate
+and percentiles at service, instance and endpoint level, the topology shows the client-side edge of every call
+with its protocol as the line type, databases, caches and brokers it calls appear as `OTLP_VIRTUAL_DATABASE`,
+`OTLP_VIRTUAL_CACHE` and `OTLP_VIRTUAL_MQ` nodes, consumers hang off their broker, and database calls slower than the
+threshold show as slow statements on the virtual database. Alarm rules reference the `otlp_*` names.
+
+#### 7.1 What a span can produce
+
+The sixteen metrics above rest on data every span carries, except the two relation families, which need a peer
+attribute. What else a rule can derive depends on which conventions the SDK emits, and the tables below are the
+catalog a rule author reads before adding a `metrics {}` block. They describe the wire format, not this design.
+
+The floor, from data every span carries:
+
+| Span data | Read as | Metric |
+|---|---|---|
+| the span itself, plus `service.name`, `service.instance.id`, `Span.name` | `meta.service`, `meta.serviceInstance`, `meta.endpoint` | call count, `function cpm`, at service, instance and endpoint |
+| `end_time_unix_nano - start_time_unix_nano` | `meta.latency` | `avg`, `max`, `min`, `percentile`, `histogram`, `apdex` |
+| `Status.code` | `meta.statusCode` | `percent`, the success rate |
+| `kind` | `meta.kind` | which side of the entity a value lands on, not a metric of its own |
+| an empty `parentSpanId` | `meta.root` | traces per minute and end-to-end trace duration, by restricting a block to roots |
+
+Beyond the floor, one attribute family at a time:
+
+| Attributes | What one more block buys |
+|---|---|
+| `service.peer.name`, its deprecated spelling `peer.service`, `server.address`, `server.port` | the relation metrics the shipped rule writes; per-peer metrics with `scope service(peer, peerLayer)` |
+| `http.request.method`, `http.route` | the endpoint name the shipped rule builds, and with it every endpoint-scoped metric |
+| `http.response.status_code` | counts split by status with `labels status: attr(...)`, hence a 4xx and a 5xx rate |
+| `http.request.body.size`, `http.response.body.size` | request and response bytes, `function sum` or `avg` |
+| `rpc.system.name`, `rpc.system`, `rpc.grpc.status_code` | the component id of the edge, current spelling first; counts split by gRPC status |
+| `peer.address` | the peer of an Envoy egress span, host and port in one string, read when a CLIENT span reports no `server.address` or `net.peer.name` |
+| `db.system.name`, `db.operation.name`, `db.collection.name`, `db.namespace` | the `OTLP_VIRTUAL_DATABASE` edge; counts and latency split by operation or by table |
+| `messaging.system`, `messaging.destination.name`, `messaging.operation.type` | the `OTLP_VIRTUAL_MQ` edge; produce and consume counts split by destination |
+| `messaging.message.body.size` | message bytes |
+| `db.query.text`, `db.statement` | a `SlowSQL` record rather than a metric, see [section 3.5](#35-output-records-outputtype) |
+| `exception` events, through `eventAttr("exception", "exception.type")` | exception counts split by type |
+| `telemetry.sdk.language`, `service.version`, `deployment.environment`, `k8s.*` | any metric above, split by a `resource(...)` label |
+| `gen_ai.*` | nothing here. The shipped rule aborts on these spans; `gen-ai-analyzer` and `virtual-gen-ai.oal` already produce `gen_ai_provider_cpm`, `_input_tokens_sum`, `_total_estimated_cost` and `gen_ai_model_ttft_avg` per provider and per model |
+
+What no rule can produce, because the data is not on the wire. [The source-mapping proposal's gap
+analysis](SWIP-otlp-trace-metrics.md#9-gaps-compared-with-agent-traces) states these against the agent path; they
+bind TAL identically, since both read the same span:
+
+- **Server-observed relation metrics.** A SERVER span carries `parentSpanId` and no caller identity, so
+ `otlp_service_relation_server_*` fills only where the caller is known another way: `User`, a configured
+ gateway, or the broker of a consumer. Every other edge carries client-observed numbers only.
+- **Endpoint-level dependency.** No parent endpoint exists on the wire, and `MeterSystem` has no endpoint-relation
+ scope to write one to; `ScopeType` stops at `SERVICE_INSTANCE_RELATION`.
+- **Message transmission latency.** The messaging conventions carry no producer timestamp.
+- **Cache command and key.** No key attribute exists, and the operation can only be inferred from
+ `db.operation.name`.
+- **Trustworthy instance metrics without `service.instance.id`.** Without it every process is the same instance, so
+ the block produces a number that is wrong rather than absent, which is why it sits behind
+ `if (meta.serviceInstance)`.
+- **Resource utilization.** CPU, memory and GC are OTLP metrics, a different signal reaching OAP another way.
+- **Anything needing a second span.** A rule sees one span and its own `ExecutionContext`, so spans per trace, error
+ propagation and critical-path metrics are out of reach. The root span's own latency is the whole trace's duration,
+ and that is the only trace-wide fact a single span holds.
+
+One caveat over every number above: head sampling in the SDK is normal, so a count is of the spans that arrived,
+not of the requests that happened. TAL runs ahead of the receiver's own sampling, see [section 2.1](#21-otlp), so it
+does not narrow the set further, but it cannot recover what the SDK dropped.
+
+### 8. Worked example
+
+The `otlp-traces` e2e runs the OpenTelemetry Demo's `frontend` (Node.js) and `productcatalogservice` (Go); one
+`GET /api/products` produces three spans, in the attribute spelling the demo's instrumentation emits:
+
+```text
+resource A: service.name=frontend service.namespace=opentelemetry-demo telemetry.sdk.language=nodejs
+ span 1 SERVER "HTTP GET" root 110 ms status UNSET
+ http.method=GET http.target=/api/products http.status_code=200 net.host.name=frontend net.host.port=8080
+ span 2 CLIENT "grpc.oteldemo.ProductCatalogService/ListProducts" parent=span 1 9 ms status UNSET
+ rpc.system=grpc rpc.service=oteldemo.ProductCatalogService rpc.method=ListProducts
+ rpc.grpc.status_code=0 net.peer.name=productcatalogservice net.peer.port=3550
+resource B: service.name=productcatalogservice telemetry.sdk.language=go
+ span 3 SERVER "oteldemo.ProductCatalogService/ListProducts" parent=span 2 (remote) 4 ms status UNSET
+ rpc.system=grpc rpc.service=oteldemo.ProductCatalogService rpc.method=ListProducts rpc.grpc.status_code=0
+ server.address=productcatalogservice server.port=3550 (the :authority; the fixture sets it, the demo's Go server omits it)
+```
+
+Neither resource carries `service.layer`, so the `layer: auto` rule runs for all three.
+
+**Span 1**, `frontend` SERVER, root. `meta` arrives as `service=frontend`, `serviceInstance=""`, `endpoint="HTTP GET"`,
+`kind=SERVER`, `statusCode=UNSET`, `latency=110`. Neither abort condition holds. `layer "OTLP_SERVICE"` sets
+`meta.layer`. The inbound branch runs; there is no `http.route`, so the endpoint stays `HTTP GET`.
+`svc` is `MeterEntity{SERVICE, frontend, OTLP_SERVICE}`; its traffic, `ServiceTraffic{frontend, OTLP_SERVICE}`, is
+emitted once. Then, at minute bucket of the span's end:
+
+| Block | Metric | Value fed to `MeterSystem` |
+|---|---|---|
+| `service_cpm` | `otlp_service_cpm` | `1` into `total`; the minute row reads `total / 1` |
+| `service_resp_time` | `otlp_service_resp_time` | `110`, averaged |
+| `service_sla` | `otlp_service_sla` | `match = true`; the row reads `10000` while every span of the minute matches |
+| `service_apdex` | `otlp_service_apdex` | `ApdexArgument{110, frontend, true}`; `frontend` has no entry in `service-apdex-threshold.yml`, so `default`, `500`, applies and the span is satisfied |
+| `service_percentile` | `otlp_service_percentile` | `BucketedValues` with `1` in bucket `250`, `0` elsewhere, ranks `50, 75, 90, 95, 99` |
+| the four `endpoint_*` blocks | `otlp_endpoint_*` | the same values on `MeterEntity{ENDPOINT, frontend, HTTP GET}`, plus `EndpointTraffic{HTTP GET}` |
+
+`meta.serviceInstance` is empty, so the instance branch is skipped and no `instance_*` values are emitted for this
+fleet; `service.instance.id` is the fix, as it is for OTLP logs.
+
+The SERVER-only block runs next. `net.host.name` and `net.host.port` are present, so `alias "frontend:8080"` emits
+`NetworkAddressAliasSetup{address=frontend:8080, representServiceId=frontend/normal}` in the minute bucket of the
+span's end. The span is root, so `fromUser` is `MeterEntity{SERVICE_RELATION, SERVER, User/UNDEFINED ->
+frontend/OTLP_SERVICE, component 49}`; its traffic is `ServiceRelationServerSideMetrics{User -> frontend,
+componentIds [49]}` and no `ServiceTraffic` for `User`, and `1` goes into `otlp_service_relation_server_cpm`. Ten
+values in all for span 1.
+
+**Span 2**, `frontend` CLIENT. The outbound branch runs. `attr("peer.service")` is empty; `rpc.system` is present, so
+`comp = component("grpc")`, which resolves `GRPC`, id `23`; no `db.*`, no `messaging.*`; `net.peer.name` is present
+under the fallback spelling, so `peer = "productcatalogservice:3550"` and `peerLayer` stays `OTLP_SERVICE`. `edge`
+is `MeterEntity{SERVICE_RELATION, CLIENT, frontend/OTLP_SERVICE -> productcatalogservice:3550/OTLP_SERVICE,
+component 23}`. Its traffic is `ServiceRelationClientSideMetrics{frontend -> productcatalogservice:3550,
+componentIds [23]}` plus `ServiceTraffic` for both ends. Three values follow: `1` into the `total` of
+`otlp_service_relation_client_cpm`, `9` averaged into `_resp_time`, `match = true` into `_sla`. The
+topology draws `frontend -> productcatalogservice:3550` as a gRPC line.
+
+**Span 3**, `productcatalogservice` SERVER. As span 1 for `productcatalogservice` with endpoint
+`oteldemo.ProductCatalogService/ListProducts` and latency 4. The span has a parent, so no `User` edge, and a server
+span cannot name its caller, so no relation. `server.address` and `server.port` are present, so
+`alias "productcatalogservice:3550"` emits `NetworkAddressAliasSetup{address=productcatalogservice:3550,
+representServiceId=productcatalogservice/normal}`, the row the next request's span 2 resolves.
+
+The `otlp-slow-sql` rule runs on all three spans as well, since they carry no `service.layer` either, and aborts on
+its first condition every time: none is a database client span. Nothing is written and no vote is cast.
+
+The result is two `OTLP_SERVICE` services with service and endpoint metrics, the `User -> frontend` edge, the
+`frontend -> productcatalogservice:3550` edge, and two alias rows. The address-named node is what the first request
+draws: when span 2 is analyzed, `productcatalogservice` has not emitted a span yet, so its name is not in
+`KnownServices`, and span 3's alias row is not in `NetworkAddressAliasCache` either, which `CacheUpdateTimer` fills
+from `network_address_alias` every 10 seconds. The next `GET /api/products` lands on
+`frontend -> productcatalogservice`: `resolveAlias("productcatalogservice:3550")` returns `productcatalogservice`,
+by now through the host rule alone, with the cache row behind it for a spelling that is not the name; the same
+`serviceRelation` builds `MeterEntity{SERVICE_RELATION, CLIENT, frontend/OTLP_SERVICE ->
+productcatalogservice/OTLP_SERVICE, component 23}`, a relation row of its own, and `ServiceTopologyBuilder` folds
+the first request's address-named edge into it at query time through the same cache. `peer.service` on the client
+remains the SDK-side alternative: had the demo set it, the first edge would have landed on the service directly.
+
+Had the same spans come from a current SDK, the attribute names would read `http.request.method`,
+`http.response.status_code`, `server.address` and `server.port`; every `attr()` in the rule lists the current name
+first and the demo's spelling second, so the entities and values are identical. One rule, one set of entities,
+across SDK generations.
+
+### 9. Runtime-rule hot update
+
+`Catalog` gains `TAL("tal")`. A `TalRuleEngine` for the catalog is modeled on `LalRuleEngine` with a
+`TalFileApplier` over `SpanFilterListener.Factory`, and borrows the metric-shape guard from `MalRuleEngine`
+because a TAL file, unlike a LAL file, owns storage: `claimedKeys` are the `<layer>:<ruleName>` pairs and the full
+metric names the file declares, so two files declaring the same metric is a cross-file collision;
+`storageImpactKeys` are the metric names added, removed or reshaped between the prior and the new content, computed
+from the declarations, which is simpler than `MalShapeExtractor` because they are literals, plus the rule names
+whose `outputType` was added, removed or changed, the same rule LAL applies because those reroute records to a
+different storage-backed type; `recordBundledClaims`
+loads the shipped file's claims at boot; compile runs in a per-file `RuleClassLoader` from `DSLClassLoaderManager`
+so a replaced bundle's classes are dropped together, and `MeterSystem.create` is called with that loader and the
+main or peer `StorageManipulationOpt`. `POST /runtime/rule/addOrUpdate?catalog=tal` follows the documented
+consistency contract: persist is commit, every node converges on its next scan, a change that adds or reshapes a
+metric is a storage change and needs `allowStorageChange`, exactly as for a MAL file. A body-only change, a new
+condition or a changed `attr()` fallback, applies without pausing anything.
+
+### 10. Live debugging
+
+`trace-analyzer` gains `TALDebug` static probes and a `TALDebugRecorder` interface, typed to `ExecutionContext`,
+`Span`, `MeterEntity` and `AcceptableValue`, with the probe sites LAL and MAL have between them: the input at the
+top of `execute`, each block, each statement when `granularity=statement`, and a terminal probe per `metrics {}`
+block carrying the metric name, the entity id and the value handed to `MeterSystem`, which is the same boundary
+MAL's `captureMeterEmit` marks. The `dsl-debugging` module gains a `TALHolderRegistry` and recorder factory, the
+static loader and the runtime-rule engine publish the per-rule `GateHolder` under `RuleKey(TAL, <file>, <rule>)`,
+and the input payload is rendered by the input's `TALSourceTypeProvider`, OTLP/JSON for an OTLP span and Zipkin
+JSON for a Zipkin one, alongside the derived `meta`; the output payload of a rule with an `outputType` is the
+builder's `outputToJson()`, as it is for LAL, and the `sink {}` probe records whether the record was written.
+Codegen injection follows `DSLDebugCodegenSwitch` as the other three DSLs do.
+`docs/en/setup/backend/admin-api/dsl-debugging-tal.md` is the operator reference, listed in `docs/menu.yml` next
+to the LAL page.
+
+A dry run needs no new endpoint: opening a debug session on `otlp-service` and sending one OTLP/JSON payload
+through `POST /v1/traces` shows every `attr()` result, every `def`, the branch taken and every metric value
+emitted, without waiting for a dashboard to fill.
+
+### 11. Self-observability
+
+On the module's telemetry: `trace_analyzer_spans` labeled by `layer` and `outcome`, one of `analyzed`, `no_rule`,
+`aborted`, `unknown_layer`, `duplicate`; `trace_analyzer_latency`, a histogram of the per-span rule evaluation,
+which is the number to watch when a rule file grows; `trace_analyzer_metrics_skipped` labeled by `reason`,
+`unknown_layer` or `bad_value`, for blocks skipped at runtime; `trace_analyzer_records` labeled by `outputType`,
+records a `sink {}` wrote; `trace_analyzer_dropped_by_persist`, spans a `persist {}` vote removed from storage; and
+`trace_analyzer_enforced`, spans an `enforcer {}` carried past the receiver's head sampling.
+The `layer` label of `trace_analyzer_spans` is joined by an `input` label, `otlp` or `zipkin`.
+
+### 12. Dashboards and menu
+
+The `OTLP_SERVICE` layer gets the standard four templates in the Horizon UI dashboard bundle, root list, service,
+instance and endpoint, built on the sixteen metrics of [section 7](#7-shipped-rule), with the topology and trace
+tabs the General dashboards have. The service list columns are `otlp_service_cpm`,
+`otlp_service_sla`, `otlp_service_resp_time` and `otlp_service_apdex`, the columns of the General
+list; because the functions and units are the same, the templates are the General templates with the metric names
+replaced, not new widget designs. A menu entry "OpenTelemetry Service" under the service group points at the layer and at the operator doc. The trace
+tab queries whichever store the deployment uses, Zipkin or `/otlp`, which is the same UI dependency the storage
+proposal records.
+
+### 13. Tests
+
+- Grammar and generator unit tests as `log-analyzer` has them: parser tests over every statement, generator tests
+ for typed `span.*` access on both input types, `meta` overwrite, `attr()` fallback order, every entity
+ constructor, every function's value type, `buckets` placement and the overflow bucket, `labels` with labeled
+ functions, `abort` in every position, `persist` voting and the `enforced` flag, output-field setters and the `sink` lifecycle for a
+ builder and for a plain `Source`, input routing by `isInstance`, and every compile-time rejection in
+ [section 4](#4-compiler-and-runtime).
+- Alias and `User` tests in `TALExecutionTest` and the worked example: the `alias` statement's row carries the
+ address, the layer's `normal` flag and the span's minute bucket, and an empty address registers nothing;
+ `resolveAlias` substitutes the represented service against a loaded cache and leaves an unknown address alone;
+ `alias` skips an address whose host, or first DNS label, names another known service, and `resolveAlias`
+ returns that service before the cache, even against a row that maps the address elsewhere; `SpanPairingTest`
+ covers both arrival orders, the consumed pair, the remembered answer, a call inside one service, root and
+ non-client spans, the guard on a learned row, a two-node transport in which both facts reach the owner and the
+ row is written there, and a `PairingFact` wire round trip; the execution test drives the pairing through
+ `resolveAlias` in both orders;
+ a root span draws `User -> service` under `User`'s non-normal id with no `ServiceTraffic` for `User`, and a span
+ with a parent draws nothing; the worked example replays span 2 after a cache reload and asserts the resolved
+ edge.
+- Metric registration tests: compiling a rule creates each declared metric once with the right function and scope,
+ branches sharing a name share a metric, conflicting shapes fail, and the runtime-rule path passes the per-file
+ loader and the main or peer storage option through.
+- A recorded trace through the shipped rule, `ShippedRuleOverRecordedTraceTest` in the OTLP receiver plugin: the
+ eight spans of one `GET /api/cart` from the OpenTelemetry Demo, kept as OTLP/JSON under the plugin's test
+ resources, fed with the real `otlp` input type and the metadata the receiver builds, in a cold pass and a warm
+ pass. It pins the edges of each pass, the alias rows including the startup race and the pairing's correction of
+ it, the metric count per span, and the route-shaped endpoint names read through the real provider.
+- Forward tests: `SpanForwardTest` and `OTLPSpanForwardTest` keep an enforced span at `sampleRate: 0`, still drop
+ it once `maxSpansPerSecond` is exhausted, and keep the existing decisions for spans that are not enforced.
+- Data-driven execution tests through `server-testing`: a `dsl/tal` loader beside `dsl/lal` and `dsl/mal`, rule
+ files under `trace-analyzer/src/test/resources/scripts/tal/` with `.input.data` companions holding OTLP/JSON
+ spans and the expected emitted metrics as `(name, entity id, value)` triples, `meta` values, abort and
+ persistence outcomes, and the records a `sink {}` wrote, asserted against a recording `MeterSystem` and
+ `SourceReceiver`. The shipped `otlp-default.yaml` is one of them, over the three spans above plus a PostgreSQL
+ client span at 30 ms and one at 900 ms, which must and must not produce a `DatabaseSlowStatement`, a Kafka
+ producer and consumer pair, a Valkey client span and an `exception` event. A Zipkin fixture, Brave-shaped JSON
+ spans, runs the same rules with `inputType: otlp, zipkin` and must produce the same entities and values as the
+ OTLP fixture for the same hop.
+- `MeterEntity` and `EntityTrafficGenerator` unit tests: ids built with each side's `normal` flag for two-layer
+ relations, `ServiceTraffic` for both ends, single-layer factories and MAL's traffic unchanged. The MAL
+ `.data.yaml` suite must pass unchanged after the move.
+- `PercentFunction` and `ApdexFunction` unit tests with the cases of the `PercentMetrics` and `ApdexMetrics` tests:
+ `combine`, `calculate`, `toHour`, `toDay`, the storage builder round trip, and for apdex the `default` and
+ per-service thresholds and the unsuccessful-span rule. A cross-check test feeds the same observations to
+ `CPMMetrics` and `sumPerMin`, `PercentMetrics` and `percent`, `ApdexMetrics` and `apdex`, and asserts equal values.
+- e2e: `otlp-traces` verifies with `swctl` that `service ly OTLP_SERVICE` lists `frontend` and
+ `productcatalogservice`, that `metrics exec` returns `otlp_service_cpm` and `otlp_endpoint_resp_time`
+ for them, and that `dependency service` shows the `User -> frontend` edge and the `frontend -> productcatalogservice`
+ edge once the alias row has reached the cache, with the first request's `frontend -> productcatalogservice:3550`
+ folded into it; the storage e2e's
+ `config-dump.yml` gains the new default; `otlp-virtual-genai` proves the GenAI listener and TAL coexist, with the
+ GenAI spans aborted by the first condition of the shipped rule.
+
+### 14. Documentation
+
+- `docs/en/concepts-and-designs/tal.md`, the language reference, structured like `lal.md`: rule files and layer
+ routing, inputs and `inputType`, `span` and `meta`, functions, filter, extractor, the `metrics` block with its
+ constructors and functions, output records and `outputType`, `sink` and `persist`, differences from LAL. Listed
+ in `docs/menu.yml` as "Analysis Traces" next to "Analysis Logs".
+- `docs/en/guides/tal-extension.md`, the developer guide for custom input and output types, the counterpart of
+ `lal-extension.md`: implementing `TALSourceTypeProvider` and `TALOutputBuilder`, registering them over
+ `META-INF/services`, and which builders serve both DSLs.
+- `docs/en/setup/backend/trace-analyzer.md`, the module configuration, next to `log-analyzer.md`;
+ `otlp-trace.md` gains a section pointing at it and describing what appears in the UI.
+- `docs/en/concepts-and-designs/runtime-rule-hot-update.md`: the new catalog and that it owns storage like MAL.
+- `docs/en/setup/backend/admin-api/dsl-debugging-tal.md`.
+- `docs/en/changes/changes.md`.
+
+### 15. What this design gives up, and what it gains
+
+Compared with the source-mapping proposal, which is the reference for parity with agent traces:
+
+| Topic | Source mapping | TAL |
+|---|---|---|
+| Metric names | `service_cpm`, `service_sla`, the `core.oal` set, in `GENERAL` | `otlp_service_cpm` and whatever the rule declares, in `OTLP_SERVICE`, computed by the same functions in the same units; General dashboards and alarm rules apply after renaming the metric, not as they are |
+| Virtual peers | `DatabaseAccess`, `CacheAccess`, `MQAccess` sources feed the existing virtual-service dashboards and slow-statement records | peers exist as topology nodes and in their virtual layer lists through the two-layer relation; their access metrics are the `otlp_service_relation_*` series on the edge, and the `core.oal` panels of the existing virtual-service dashboards stay empty for them, while the slow-statement panel fills from `otlp-slow-sql`. Per-peer metrics are one more [...]
+| Records | `DatabaseSlowStatement`, `CacheSlowAccess` | `DatabaseSlowStatement` through `outputType: SlowSQL`, shipped; `CacheSlowAccess` needs a builder, a follow-up; any other record through a custom `TALOutputBuilder` |
+| Other trace protocols | OTLP only | OTLP shipped; Zipkin through `inputType: zipkin` on the same rules |
+| Endpoint relations | `EndpointRelation` from `User` | no endpoint-relation scope in `MeterSystem` |
+| Adding a convention or a peer kind | a Java change to the rule schema, or a new key in it | an edit to the rule file, hot-applied |
+| Changing what is measured | not possible; `core.oal` decides | any function over any value on any entity, declared where the value is computed |
+| Operator tooling | none | runtime-rule hot update with a metric shape guard, dsl-debugging sessions, generated-class dumps, data-driven test harness |
+| Shared limits | one span at a time, no caller identity on the server side, endpoint names as good as the instrumentation's, sampling at the SDK hides requests, exporter retries double count without a seen-set | the same |
+
+The trade is a fixed, agent-parity metric set against an editable one with the tooling the other DSLs have. The
+`otlp_*` naming and the separate layer are the visible cost, and they are also what keeps the two worlds from
+silently double counting a service that runs both an agent and an SDK.
+
+## Imported Dependencies libs and their licenses
+
+None. ANTLR4 runtime and Javassist are already dependencies of the analyzer modules.
+
+## Compatibility
+
+- The `trace-analyzer` module is present by default with the shipped rule active, so deployments that send OTLP
+ traces gain `OTLP_SERVICE` entities and the sixteen `otlp_*` metrics on upgrade. Setting
+ `SW_TRACE_TAL_FILES` empty keeps today's behavior. The metrics are new measures, indices or tables, created at
+ boot like any new MAL rule's.
+- `OTLP_SERVICE` takes ordinal `52`, the next free built-in ordinal. Every OAP node must run the same build; that
+ is already true for every layer.
+- `receiver-otel` requires `trace-analyzer`. Selecting `trace-analyzer` out with `-` is not supported; disabling the
+ analysis is done through `talFiles`.
+- `MeterEntity` gains `destLayer` and two factory overloads; the existing factories and ids are unchanged. Entity
+ traffic generation moves from `meter-analyzer` to `server-core`; MAL calls the moved code and behaves as before.
+ MAL's grammar and rule files are untouched.
+- `MeterSystem` gains two functions, `percent` and `apdex`, registered by the existing annotation scan. No existing
+ function changes. `ApdexThresholdConfig` is shared with `ApdexMetrics`, so one `service-apdex-threshold.yml` and
+ one dynamic-configuration key serve agent and OTLP services alike. `cpm` in a TAL rule is `sumPerMin`; no new
+ class and no change to `SumPerMinFunction`.
+- `Catalog` gains one value; the runtime-rule REST surface accepts it; existing catalogs are unaffected.
+- `SpanListener`, `OTLPSpanReader`, `SpanListenerResult` and the Zipkin conversion are untouched. Phase-one
+ listeners run before TAL and their persistence and tag decisions are merged with TAL's.
+- `SpanForward.getSampledTraces` and `OTLPSpanForward.send` gain an enforced flag that skips the trace-id check.
+ With no rule voting nothing is enforced, so their decisions are unchanged.
+- Spans arriving over the Zipkin protocol are analyzed only by rules that declare `inputType: zipkin`; the shipped
+ rules do not, so Zipkin deployments see no change until they opt in. `receiver-zipkin` requires
+ `trace-analyzer`. The Zipkin receiver is untouched: no rule sees a Zipkin span in this proposal, and the
+ provider that would change that is reserved, not shipped. A Zipkin span has no instance, no resource and no
+ scope, so rules that read those would get empty values when it lands.
+- `TALOutputBuilder` is a new interface in `server-core`. `DatabaseSlowStatementBuilder` implements it beside
+ `LALOutputBuilder`; its LAL behavior is unchanged. A rule with `outputType` writes records through
+ `SourceReceiver` exactly as a LAL rule does, and a `Source`-path `outputType` can reach `core.oal`; the shipped
+ rules use only `SlowSQL`.
+- `log-analyzer` is untouched. TAL compiles with its own expression codegen rather than a module shared with LAL,
+ so no TAL change can reach log parsing; the cost is a duplicated engine that has to be kept in step by hand.
+- Metrics are exact only if OAP sees every span. SDK head sampling hides requests; exporter retries can double
+ count unless `dedupWindow` is set, and then only within one node.
+- A GENERAL service and an OTLP_SERVICE service with the same name are one entity in two layers.
+
+## General usage docs
+
+With the defaults nothing needs to be enabled. After an OpenTelemetry SDK exports traces, its services appear under
+the OpenTelemetry Service menu with load, latency, success rate and percentile dashboards at service, instance and
+endpoint level, the topology shows the calls between them and to their databases, caches and brokers, and alarm
+rules can reference the `otlp_*` metrics.
+
+To change what is measured, edit or add a rule file:
+
+```yaml
+trace-analyzer:
+ selector: default
+ default:
+ talFiles: otlp-default,my-rules
+```
+
+A rule that counts failed HTTP client calls by exception type and status code, keeps every failed span, and
+samples the rest:
+
+```yaml
+# tal/my-rules.yaml
+metricPrefix: otlp
+rules:
+ - name: failed-http-calls
+ layer: auto
+ dsl: |
+ filter {
+ if (meta.kind != "CLIENT" || !hasAttr("http.request.method", "http.method")) {
+ abort {}
+ }
+ extractor {
+ layer "OTLP_SERVICE"
+ if (meta.statusCode == "ERROR") {
+ tag 'exception.type': eventAttr("exception", "exception.type")
+ metrics {
+ name "http_client_failures"
+ scope service(meta.service, meta.layer)
+ function sumLabeled
+ labels exception: eventAttr("exception", "exception.type"),
+ status: attr("http.response.status_code", "http.status_code")
+ value 1
+ }
+ }
+ }
+ persist {
+ if (meta.statusCode == "ERROR") {
+ enforcer {}
+ } else {
+ sampler {
+ rateLimit("${meta.service}:http-client") {
+ rpm 600
+ }
+ }
+ }
+ }
+ }
+```
+
+Apply without a restart and watch it run:
+
+```bash
+# The rule YAML is the raw body; catalog and name are query parameters, as for every other catalog.
+# The file declares a new metric, which is a storage change and needs the explicit opt-in, like a MAL file.
+curl -X POST 'http://oap:17128/runtime/rule/addOrUpdate?catalog=tal&name=my-rules&allowStorageChange=true' --data-binary @my-rules.yaml
+# Open a statement-level debug session on the new rule and drive one request through the SDK.
+curl -X POST 'http://oap:17128/dsl-debugging/session?catalog=tal&name=my-rules&ruleName=failed-http-calls&clientId=me&granularity=statement'
+```
+
+The catalog-in-path alias the plugin offers for the other DSLs gets a counterpart,
+`/runtime/tal/{addOrUpdate,inactivate,delete}`. For a shipped rule the debug session names the file with its
+extension, `name=otlp-default.yaml`; for a runtime-rule entry the entry name, `name=my-rules`; `RuleKey`
+canonicalizes both to one key.
+
+To place a fleet in another layer, stamp `service.layer` on its resources and declare the rules under that layer,
+passing the layer to the entity constructors. To recognize an SDK that still emits an old attribute name, add the
+spelling to the `attr()` call that reads it. To give a new database or broker its own icon, make sure
+`component-libraries.yml` has an entry whose name matches the `db.system.name` or `messaging.system` value,
+case-insensitively; `component()` does the rest.
diff --git a/docs/en/swip/SWIP-otlp-trace-metrics.md b/docs/en/swip/SWIP-otlp-trace-metrics.md
new file mode 100644
index 0000000000..04c04e68d1
--- /dev/null
+++ b/docs/en/swip/SWIP-otlp-trace-metrics.md
@@ -0,0 +1,747 @@
+# Metrics and Topology from OTLP Traces
+
+## Motivation
+
+Traces reported by SkyWalking agents drive the whole analysis platform. `TraceAnalyzer` walks every span of a
+segment, `RPCAnalysisListener` turns entry and exit spans into `Service`, `ServiceInstance`, `Endpoint`,
+`ServiceRelation`, `ServiceInstanceRelation` and `EndpointRelation` sources, the virtual-service processors turn
+database, cache, message-queue and GenAI calls into virtual services with their access metrics and slow-statement
+records, and OAL aggregates all of it into `service_cpm`, `service_resp_time`, `service_sla`, the percentiles, the
+endpoint metrics, the topology and everything alarms and dashboards are built on.
+
+Traces reported over OTLP drive none of it. Whether they are converted to Zipkin, as today, or stored natively, as
+[the native OTLP trace storage proposal](SWIP-otlp-native-trace.md) describes, the only analysis an OTLP span gets is
+the name catalogs of its trace store and the two special-purpose span listeners that exist for GenAI and iOS
+attributes. An OpenTelemetry SDK user sees their services nowhere in the SkyWalking service list, gets no topology,
+no RED metrics, no virtual database or broker nodes, and cannot alarm on any of it. The OpenTelemetry Collector's
+`spanmetrics` and `servicegraph` connectors can produce metrics that a MAL rule could ingest, but that path needs a
+collector in front of OAP, yields dimensions defined by collector configuration rather than SkyWalking entities, and
+never produces the per-span sources the General-layer dashboards, the virtual services and the alarm rules were
+built around.
+
+The gap is not the aggregation layer, which is protocol-agnostic. It is the step that reads a span and emits the
+sources. This proposal adds that step for OTLP spans, as a `SpanListener` that maps each span onto the same sources
+the agent path emits, driven by a rule file that carries the OpenTelemetry semantic-convention knowledge.
+
+OTLP spans differ from agent segments in three ways the design has to absorb:
+
+| Agent segment carries | OTLP span carries | Consequence |
+|---|---|---|
+| `SegmentReference` with the caller's service, instance, endpoint and the address the caller used | `parentSpanId` only | A server-side span cannot name its caller. Topology edges come from the client side of each hop |
+| `SpanLayer` and `componentId` | Semantic-convention attributes: `http.*`, `rpc.*`, `db.*`, `messaging.*`, `gen_ai.*`, `faas.*` | Request type, layer and component are derived from attribute families, by configuration |
+| One `peer` address | `peer.service`, `server.address`, `server.port`, or for Envoy an `upstream_cluster` | Peer resolution is a rule, and differs per layer |
+
+A fourth difference is the layer of the reporting service itself. Agents only ever produce GENERAL or FAAS. OTLP
+resources carry attributes that identify a service mesh sidecar, a function runtime or an explicit
+`service.layer`, so the layer becomes a per-resource decision.
+
+## Architecture Graph
+
+```text
+OTLP/gRPC, OTLP/HTTP
+ │
+ v
+OpenTelemetryTraceHandler.processExport
+ │ for every span, before head sampling and before storage of either mode:
+ v
+SpanListenerManager.notifyOTLPPhase ───────────────────────────────────────────────┐
+ │ │
+ ├─> IOSHTTPSpanListener, IOSMetricKitSpanListener, GenAISpanListener (existing) │
+ │ │
+ └─> OTLPTraceAnalysisListener (new module oap-server/analyzer/otlp-trace-analyzer)
+ │ otlp-trace-analysis.yml
+ │ aliases ─ service identity & layer ─ request type ─ status ─ peers ─ callers
+ │
+ ├─ resource ──> layer (GENERAL | FAAS | MESH | explicit service.layer)
+ ├─ SERVER / CONSUMER span ──> callingIn: Service, ServiceInstance, Endpoint,
+ │ ServiceRelation from User / gateway / broker
+ ├─ CLIENT / PRODUCER span ──> callingOut: ServiceRelation, ServiceInstanceRelation,
+ │ ServiceMeta + DatabaseAccess | CacheAccess | MQAccess ...
+ ├─ SERVER span ──> NetworkAddressAliasSetup (server.address:port -> this service)
+ └─ INTERNAL span ──> nothing, or a logic Endpoint when opted in
+ │
+ v
+ SourceReceiver ──> OAL (core.oal, unchanged) ──> metrics, topology, alarms
+```
+
+The listener sits in the existing phase-one hook, so it runs on every span regardless of the trace store, of
+`otlpTraceStorage`, and of head sampling, which `OTLPSpanForward` and `SpanForward` apply afterwards. That is the
+same ordering the agent path has: only `SegmentAnalysisListener` consults the sampler, and it decides storage, not
+metrics.
+
+## Proposed Changes
+
+### 1. Extension point and module
+
+A new analyzer module, `oap-server/analyzer/otlp-trace-analyzer`, alongside `gen-ai-analyzer` and `ios-analyzer`,
+containing `OTLPTraceAnalysisListener implements SpanListener`, registered through
+`META-INF/services/org.apache.skywalking.oap.server.core.trace.SpanListener`. The agent-analyzer listeners
+`CommonAnalysisListener`, `RPCAnalysisListener` and `SegmentAnalysisListener` are not touched.
+
+`requiredModules()` declares `CoreModule.NAME`, for `SourceReceiver`, `NamingControl`, `NetworkAddressAliasCache`
+and `IComponentLibraryCatalogService`, and `AnalyzerModule.NAME`, for the shared configuration service in
+[section 4](#4-shared-configuration-from-the-analyzer-module). The listener is inert unless enabled:
+
+```yaml
+receiver-otel:
+ selector: ${SW_OTEL_RECEIVER:default}
+ default:
+ # Derive SkyWalking sources (services, endpoints, topology, virtual databases, brokers, caches) from
+ # OTLP spans, the way the agent trace analyzer does for segments. Independent of otlpTraceStorage.
+ otlpTraceAnalysis: ${SW_OTEL_TRACE_ANALYSIS:false}
+ otlpTraceAnalysisRules: ${SW_OTEL_TRACE_ANALYSIS_RULES:otlp-trace-analysis.yml}
+ # Spans seen within this window (seconds) are analyzed once, even if a retrying exporter delivers them again.
+ # 0 disables the check. Bounded by otlpTraceAnalysisDedupCapacity entries per OAP node.
+ otlpTraceAnalysisDedupWindow: ${SW_OTEL_TRACE_ANALYSIS_DEDUP_WINDOW:300}
+ otlpTraceAnalysisDedupCapacity: ${SW_OTEL_TRACE_ANALYSIS_DEDUP_CAPACITY:1000000}
+```
+
+The listener reads its switch and rule path from `OtelMetricReceiverConfig` through the module manager at `init`,
+so the receiver owns the configuration and the module owns the behavior. `SpanListenerResult.CONTINUE` is always
+returned: this listener neither vetoes persistence nor injects attributes.
+
+### 2. `OTLPSpanReader` additions
+
+The reader exposes `traceId`, `spanId`, `spanName`, `spanKind`, the two timestamps and `getAttribute(key)` today.
+The native storage proposal adds `Map<String, String> attributes()`. This proposal adds, all as default methods so
+existing implementations compile:
+
+| Method | Returns | Used for |
+|---|---|---|
+| `parentSpanId()` | lowercase hex, empty for a root span | caller resolution, section 6 |
+| `statusCode()` | the OTLP enum name, `STATUS_CODE_UNSET`, `STATUS_CODE_OK`, `STATUS_CODE_ERROR` | status |
+| `statusMessage()` | the status message | GenAI and error records |
+| `attributes()` | every span attribute, values rendered as strings | rule matching, tags |
+
+`spanKind()` already returns the proto enum name, `SPAN_KIND_CLIENT` rather than `CLIENT`; the listener matches on
+those names.
+
+### 3. Shared source builders
+
+`EndpointSourceBuilder` and `RPCTrafficSourceBuilder` in `agent-analyzer` are the only code that knows how to fill
+the six traffic sources consistently, including `NamingControl` formatting in `prepare()`, the null rules for
+instance and endpoint relations, and the `key:value` tag rendering. They are package-private and depend only on
+`server-core` types and `KeyStringValuePair`, which `server-core` already imports. They move to
+`org.apache.skywalking.oap.server.core.source.builder` in `server-core` and become public. `RPCAnalysisListener`
+and the logic-endpoint code update their imports; no behavior changes. The OTLP listener then produces exactly the
+objects the agent path produces, with the same formatting.
+
+`NetworkAddressAliasSetup` is reused as is for address registration, see section 6.
+
+### 4. Shared configuration from the analyzer module
+
+Three settings the agent analyzer owns are needed unchanged: the uninstrumented gateways from `gateways.yml`
+(`UninstrumentedGatewaysConfig`), and the slow thresholds `slowDBAccessThreshold`, `slowCacheReadThreshold` and
+`slowCacheWriteThreshold` with their dynamic-configuration watchers. Duplicating their parsing would give operators
+two places to configure one thing. `AnalyzerModule` gains a service, `TraceAnalysisConfigService`, exposing
+`isAddressConfiguredAsGateway(address)`, `dbLatencyThreshold(type)`, `cacheReadLatencyThreshold(type)` and
+`cacheWriteLatencyThreshold(type)`. `AnalyzerModuleProvider` is its only provider and registers it; the
+`server-tools` data generator references the module but does not provide it.
+
+### 5. The rule file
+
+`otlp-trace-analysis.yml` ships in `server-starter/src/main/resources`. Every semantic-convention name lives here
+and not in Java, because the messaging, FaaS and GenAI conventions are still at Development stability and the
+database conventions were renamed when they stabilized in 1.30. The `aliases` section is what lets a mixed fleet of
+SDK versions land on one set of entities.
+
+```yaml
+# Matching vocabulary, used everywhere below:
+# resource: / span: which attribute set to look at
+# key attribute key, resolved through `aliases` (current name first, then old spellings)
+# exists | equals | in | matches one predicate per condition; `matches` is a Java regex, full match
+# anyOf / allOf combine conditions; a bare condition is allOf of one
+
+# 1. Attribute aliases: current name first, then the deprecated spellings older SDKs still emit.
+aliases:
+ db.system.name: [db.system]
+ db.query.text: [db.statement]
+ db.operation.name: [db.operation]
+ db.namespace: [db.name]
+ db.collection.name: [db.sql.table]
+ messaging.operation.type: [messaging.operation]
+ messaging.consumer.group.name: [messaging.kafka.consumer.group]
+ messaging.kafka.offset: [messaging.kafka.message.offset]
+ gen_ai.provider.name: [gen_ai.system]
+ http.request.method: [http.method]
+ http.response.status_code: [http.status_code]
+ server.address: [net.peer.name, net.host.name]
+ server.port: [net.peer.port, net.host.port]
+ client.address: [http.client_ip]
+ network.peer.address: [net.sock.peer.addr, net.peer.ip]
+
+# 2. The reporting service: identity and layer, decided once per resource.
+service:
+ name:
+ from: [service.name, faas.name, k8s.deployment.name, process.executable.name]
+ # Optional SkyWalking group prefix, `<group>::<name>`, taken from service.namespace. Off by default:
+ # peer.service values and dialed addresses do not carry the namespace, so enabling it needs both sides
+ # of every hop to be named the same way.
+ group: { from: service.namespace, enabled: false }
+ instance:
+ from: [service.instance.id, service.instance, k8s.pod.name, host.name]
+ default: unknown
+ # Instance properties, emitted once per minute per instance as ServiceInstanceUpdate; `language` drives
+ # the icon in the service and instance lists and must be a Language enum name.
+ properties:
+ language: { from: telemetry.sdk.language, map: { java: JAVA, dotnet: DOTNET, nodejs: NODEJS, python: PYTHON, ruby: RUBY, go: GO, php: PHP }, default: UNKNOWN }
+ hostname: { from: host.name }
+ ipv4: { from: host.ip }
+ namespace: { from: k8s.namespace.name }
+ Process No.: { from: process.pid }
+ OS Name: { from: os.type }
+ copyRemaining: true # every other resource attribute is copied under its own key
+ layer:
+ # An explicit resource attribute wins over the rules. An unknown value logs a warning and
+ # falls through to the rules instead of dropping the span, unlike the OTLP logs path.
+ attribute: service.layer
+ rules:
+ - layer: MESH
+ # ALS is the source of truth for MESH metrics and Istio samples tracing at 1% by default,
+ # so mesh spans are stored and catalogued but produce no sources unless this is flipped.
+ metrics: false
+ when:
+ anyOf:
+ - resource: { key: telemetry.sdk.name, equals: envoy }
+ - span: { key: istio.canonical_service, exists: true }
+ # Envoy's resource has no service.instance.id; the pod is the third field of node_id.
+ instance:
+ from: node_id
+ matches: '[^~]*~[^~]*~(?<pod>[^.~]+)\.[^~]*~.*'
+ format: '${pod}'
+ # Sidecar client spans carry no peer.service; the destination comes from Envoy's cluster
+ # name, rendered in the ALS naming shape `<canonical-name>.<namespace>`.
+ peer:
+ from: upstream_cluster
+ matches: 'outbound\|\d+\|[^|]*\|(?<name>[^.]+)\.(?<namespace>[^.]+)\.svc\..*'
+ format: '${name}.${namespace}'
+ - layer: FAAS
+ when:
+ resource: { key: faas.name, exists: true }
+ endpoints: false # mirrors RPCAnalysisListener.build(): no Endpoint source for FAAS
+ - layer: GENERAL
+ default: true
+
+# 3. Request type. A span may carry several families; the first match in `precedence` wins.
+requestType:
+ precedence: [GenAI, MQ, DATABASE, RPC, HTTP]
+ GenAI: { span: { key: gen_ai.provider.name, exists: true } }
+ MQ: { span: { key: messaging.system, exists: true } }
+ DATABASE: { span: { key: db.system.name, exists: true } }
+ RPC: { span: { key: rpc.system, exists: true } }
+ HTTP: { span: { key: http.request.method, exists: true } }
+
+# 4. Status, latency and endpoint naming.
+status:
+ error:
+ anyOf:
+ - status.code: ERROR
+ # - span: { key: http.response.status_code, matches: '5\d\d' } # opt in: a bare 5xx is an error
+ httpResponseStatusCode: http.response.status_code
+ rpcStatusCode: rpc.grpc.status_code
+latency:
+ from: end_time_unix_nano - start_time_unix_nano
+ unit: ms # rounded, clamped to [0, Integer.MAX_VALUE]
+endpoint:
+ name: span.name # already `{method} {route}` per the HTTP conventions; NamingControl applies
+
+# 5. Peers: what a CLIENT / PRODUCER span calls, and what a CONSUMER span consumed from.
+peers:
+ address:
+ from: [peer.service, server.address] # peer.service wins; neither present: span skipped
+ portFrom: server.port
+ aliasLookup: true # resolve through NetworkAddressAliasCache
+ registerServerAddress: true # SERVER spans register server.address:port for their service
+ gateways: gateways.yml # listed addresses become VIRTUAL_GATEWAY on both sides
+ virtual:
+ - layer: VIRTUAL_CACHE
+ when: { span: { key: db.system.name, in: [redis, valkey, memcached] } }
+ component:
+ from: db.system.name
+ map: { redis: Redis, valkey: Redis, memcached: Memcached }
+ nameFallback: '${db.system.name}-local'
+ operation:
+ from: db.operation.name
+ read: [GET, MGET, HGET, HGETALL, HMGET, LRANGE, LINDEX, SMEMBERS, SISMEMBER, ZRANGE, ZSCORE, EXISTS, TTL, SCAN, KEYS, GETS]
+ write: [SET, SETEX, SETNX, MSET, HSET, HMSET, HDEL, DEL, INCR, INCRBY, DECR, LPUSH, RPUSH, LPOP, RPOP, SADD, SREM, ZADD, ZREM, EXPIRE, CAS, ADD, REPLACE, APPEND]
+ command: db.operation.name
+ # Thresholds: slowCacheReadThreshold / slowCacheWriteThreshold keyed by the system value.
+ - layer: VIRTUAL_DATABASE
+ when: { span: { key: db.system.name, exists: true } }
+ component:
+ from: db.system.name
+ map:
+ postgresql: PostgreSQL
+ mysql: Mysql
+ mariadb: Mariadb
+ oracle.db: ORACLE
+ microsoft.sql_server: SqlServer
+ mongodb: MongoDB
+ cassandra: Cassandra
+ elasticsearch: Elasticsearch
+ clickhouse: ClickHouse
+ h2database: H2
+ sqlite: SQLite
+ influxdb: InfluxDB
+ hbase: HBase
+ neo4j: Neo4j
+ default: Unknown
+ nameFallback: '${db.system.name}-local'
+ statement: db.query.text
+ # Thresholds: slowDBAccessThreshold keyed by the system value (`default:200,mongodb:100`).
+ - layer: VIRTUAL_MQ
+ when: { span: { key: messaging.system, exists: true } }
+ component:
+ from: messaging.system
+ map: { kafka: Kafka, rabbitmq: RabbitMQ, rocketmq: RocketMQ, pulsar: Pulsar, activemq: ActiveMQ, nats: NATS }
+ default: Unknown
+ endpoint: messaging.destination.name
+ operation:
+ produce: { kind: PRODUCER }
+ consume: { kind: CONSUMER }
+ ignore: { span: { key: messaging.operation.type, in: [receive, settle, create] } }
+ # transmission latency has no source attribute in the messaging conventions; left unset.
+ # A batch `process` span (messaging.batch.message_count > 1) counts as one access, as one agent span does.
+ - layer: VIRTUAL_GENAI
+ when: { span: { key: gen_ai.provider.name, exists: true } }
+ name: gen_ai.provider.name # the VIRTUAL_GENAI service GenAIMeterAnalyzer creates, so the edge lands on it
+ handler: gen-ai-analyzer # access metrics come from GenAISpanListener
+ - layer: FAAS
+ when: { span: { key: faas.invoked_name, exists: true } }
+ name: faas.invoked_name
+ - layer: GENERAL
+ when:
+ anyOf:
+ - span: { key: rpc.system, exists: true }
+ - span: { key: http.request.method, exists: true }
+ component:
+ from: rpc.system
+ map: { grpc: GRPC, apache_dubbo: Dubbo }
+ default: http # plain HTTP calls; the topology line type reads `http`
+ - layer: UNDEFINED
+ default: true
+
+# 6. Callers of SERVER / CONSUMER spans. No SegmentReference exists, so the caller is known
+# only for a trace root or a configured gateway.
+callers:
+ rootSpan: User # no parentSpanId: the end user, as a ref-less entry today
+ remoteParent: none # Service/Instance/Endpoint sources only, no server-side relation
+ gatewayFromClientAddress: true # client.address listed in gateways.yml: caller is that gateway
+ # Opt in when callers stamp their identity into the request, e.g. W3C Baggage copied onto the server span
+ # by an SDK extension or a collector processor. Names the caller and restores the server-side relations.
+ fromAttributes:
+ enabled: false
+ service: sw.caller.service
+ instance: sw.caller.instance
+ endpoint: sw.caller.endpoint
+
+# 7. INTERNAL spans produce nothing by default. Opt in to logic endpoints, the counterpart of the
+# agents' `x-le` tag, by marking the spans that should count.
+internal:
+ logicEndpoints:
+ enabled: false
+ when: { span: { key: skywalking.logic_endpoint, equals: 'true' } }
+```
+
+The file carries no thresholds and no gateway list of its own. Slow database and cache access keep using the core
+`slowDBAccessThreshold`, `slowCacheReadThreshold` and `slowCacheWriteThreshold` settings, keyed by the
+`db.system.name` value, and `gateways.yml` stays the single source for uninstrumented gateways. Every `component`
+name in the file resolves through `IComponentLibraryCatalogService.getComponentId`, so the topology icons and the
+`database_access_*`, `cache_*` and `mq_*` OAL metrics need no change. The file is loaded at startup; hot reload can
+follow the sampling policy's `ConfigChangeWatcher` pattern later.
+
+The file is validated when it is loaded, and OAP refuses to start on a bad one rather than analyzing with a partial
+rule set: a YAML parse error, a layer name `Layer.nameOf` does not know, a component name the catalog does not
+resolve, a `matches` regex that does not compile, a `format` referencing a group the regex does not define, or a
+`requestType.precedence` entry with no matching definition. The error names the section and the offending value.
+Regexes are compiled once at load; per span, the listener builds the attribute map once and evaluates the rules in
+order, so the cost is linear in the number of attributes plus the number of rules and independent of sampling.
+
+### 6. The analysis, span by span
+
+The listener resolves the reporting service once per resource: name, instance and layer from
+[section 5 of the rule file](#5-the-rule-file), all through `NamingControl`. A resource with no resolvable name is
+skipped, as the OTLP handler already skips it. It then dispatches on the span kind.
+
+| Kind | Builder | Sources emitted | Caller or peer |
+|---|---|---|---|
+| SERVER, CONSUMER | `callingIn`, `DetectPoint.SERVER` | `Service`, `ServiceInstance`, `Endpoint` unless the layer says `endpoints: false`; `ServiceRelation`, `ServiceInstanceRelation` and `EndpointRelation` only when a caller is known | root span: `User` in UNDEFINED, as a reference-less entry span today. `client.address` in `gateways.yml`: that VIRTUAL_GATEWAY. CONSUMER: the broker as a VIRTUAL_MQ caller, as the MQ branch of `parseEntry` does. Otherwise no caller and no relation |
+| SERVER | alias registration | `NetworkAddressAliasSetup` mapping `server.address:server.port` to this service and instance | replaces what `networkAddressUsedAtPeer` provides for agents |
+| CLIENT, PRODUCER | `callingOut`, `DetectPoint.CLIENT` | `ServiceRelation`; `ServiceInstanceRelation` when the peer resolved to a real instance; for a virtual peer also `ServiceMeta` and the access source of its kind, `DatabaseAccess` and `DatabaseSlowStatement`, `CacheAccess` and `CacheSlowAccess`, `MQAccess`, `MQEndpointAccess` and `EndpointMeta` | `peer.service`, else `server.address:server.port`, resolved through `NetworkAddressAliasCache`; unresolved addresses become the virtual pe [...]
+| CLIENT or CONSUMER with `messaging.operation.type` `receive` | none | none | a poll is transport bookkeeping, whichever kind the SDK gives the wait |
+| INTERNAL | none, or `EndpointSourceBuilder` | a `RequestType.LOGIC` `Endpoint` when `internal.logicEndpoints` opts the span in | none |
+
+Two sources are emitted per resource on every span, independent of the kind, and deduplicated per minute by OAL:
+`ServiceMeta{name, layer}` and `ServiceInstanceUpdate{service, instance, properties}`. Without them a service that
+only ever sends CLIENT or PRODUCER spans, a batch job publishing to Kafka for instance, would exist as a relation
+source but never in the service list, because `ServiceTraffic` and `InstanceTraffic` are created by these sources
+and by the calling-in path only. The properties come from the `service.instance.properties` rules:
+`telemetry.sdk.language` mapped onto the `Language` enum drives the language icon, and the remaining resource
+attributes appear on the instance page the way agent-reported properties do.
+
+`DatabaseSlowStatement.traceId` and the GenAI records carry the OTLP trace id in hex. The UI links from them to the
+trace resolve only where the service's trace tab does, see the Compatibility section.
+
+The common attributes follow `setPublicAttrs` in the agent path: latency is the nanosecond difference rounded to
+milliseconds and clamped to `[0, Integer.MAX_VALUE]`, status is false when `status.code` is `STATUS_CODE_ERROR`,
+`httpResponseStatusCode` and `rpcStatusCode` come from the configured attributes, `type` from the request-type
+precedence, and every span attribute is added as a `key:value` tag plus the `originalTags` map. The time bucket is
+the minute of the span's start.
+
+One step has no counterpart in the agent path. OTLP exporters retry a batch on transient failure, in SDKs and in
+the collector, and a retry after a transport timeout re-delivers spans OAP has already processed. The trace store
+deduplicates them by trace id and span id; the sources would not be, and every retried request would be counted
+twice in `service_cpm`, `service_sla` and the relation metrics. The listener therefore keeps a seen-set of
+`(traceId, spanId)` for `otlpTraceAnalysisDedupWindow` seconds, capped at `otlpTraceAnalysisDedupCapacity`
+entries, and analyzes a span only on first sight. The window defaults to the collector exporter's default maximum
+retry time. The set is per OAP node: a retry that lands on another node behind a load balancer is not caught, which
+is why the export response must never invite a retry of accepted spans, see the `partial_success` handling in the
+native storage proposal.
+
+Two decisions differ from the agent path and are deliberate:
+
+- A CLIENT span to a cache gets `RequestType.DATABASE`, because `db.system.name` is what identifies it. The agent
+ path types a `SpanLayer.Cache` span as RPC, since `RequestType` has no cache value. Dashboards that split by type
+ should know this.
+- A SERVER span with a remote parent emits no server-side relation rather than a false `User` edge. Every hop's edge
+ comes from its client side, so the topology still forms. The `service_relation_server_*` metrics populate only for
+ `User` and gateway callers.
+
+### 7. Layer resolution
+
+The reporting service's layer is decided per resource in this order: the `service.layer` resource attribute if
+present and known, then the first matching rule, then GENERAL. This is the same convention the OTLP logs handler
+uses, with one difference: an unknown `service.layer` value is logged and falls through instead of dropping the
+data.
+
+MESH is the case that matters most. Envoy's OpenTelemetry tracer stamps its resource with `telemetry.sdk.name`
+`envoy`, and Istio adds `istio.canonical_service` and its siblings as span tags, so sidecar spans are recognized
+without configuration. Their `service.name` is `<canonical-name>.<namespace>`, the shape `k8sServiceNameRule`
+gives ALS services, so mesh spans attach to the MESH services ALS already created. Because `ServiceTraffic`
+identifies a service by name plus layer, an application that also runs an SDK becomes a separate GENERAL entity, and
+the hierarchy joins the two through `K8S_SERVICE`. MESH metrics default to off: ALS is the full-fidelity source, and
+Istio samples tracing at one percent by default, so span-derived numbers would contradict it. With `metrics: true`,
+the `peer` extractor turns `outbound|9080|v2|reviews.default.svc.cluster.local` into `reviews.default`, and the
+`instance` extractor takes the pod from `node_id`.
+
+The virtual layers are decided per span, not per resource, from the `peers.virtual` list. Redis, Valkey and
+Memcached are listed under `db.system.name` by the conventions but belong to VIRTUAL_CACHE, so the cache rule is
+evaluated before the database rule. Every peer layer the agent path can produce has a rule: VIRTUAL_DATABASE,
+VIRTUAL_CACHE, VIRTUAL_MQ, VIRTUAL_GENAI, VIRTUAL_GATEWAY, FAAS, GENERAL and UNDEFINED.
+
+### 8. Worked example
+
+The [native storage proposal's worked example](SWIP-otlp-native-trace.md#worked-example) is one HTTP hop. The
+example for this proposal is the OpenTelemetry Demo's checkout flow, nine spans over two traces: `frontend` calls
+`checkout` over gRPC, `checkout` calls `cart`, `cart` reads Valkey, `checkout` publishes to Kafka, and `accounting`
+polls, processes and inserts into PostgreSQL. The consumer side is its own trace linked to the producer span, the
+messaging conventions' default. The sources, with the ids `IDManager` derives:
+
+| Span | Sources |
+|---|---|
+| every span of every resource | `ServiceMeta{<service>, GENERAL}` and `ServiceInstanceUpdate{<service>, <instance>, {language: NODEJS or GO or DOTNET, hostname, namespace: otel-demo, Process No., ...}}`, deduplicated per minute |
+| `frontend` SERVER `POST /api/checkout`, root | `Service frontend` (GENERAL, `ZnJvbnRlbmQ=.1`), `ServiceInstance frontend-6c8d7f9b4-x2k9p`, `Endpoint POST /api/checkout`, `ServiceRelation User -> frontend` (SERVER, HTTP, 249 ms, status true, HTTP 200, component 49), `ServiceInstanceRelation`, `EndpointRelation User -> POST /api/checkout`; `NetworkAddressAliasSetup frontend:8080 -> frontend` |
+| `frontend` CLIENT `oteldemo.CheckoutService/PlaceOrder` | `ServiceRelation frontend -> checkout` (CLIENT, RPC, 239 ms, `rpcStatusCode "0"`, component 23, `ZnJvbnRlbmQ=.1-Y2hlY2tvdXQ=.1`), `ServiceInstanceRelation`; `checkout:8080` resolved through the alias the checkout SERVER span registered |
+| `checkout` SERVER `PlaceOrder`, remote parent | `Service checkout`, `ServiceInstance`, `Endpoint`, 237 ms; no relation |
+| `checkout` CLIENT `GetCart`, `cart` SERVER `GetCart` | as the two rows above, `checkout -> cart`, 4 ms and 2 ms |
+| `cart` CLIENT `HGET` | `ServiceMeta valkey-cart:6379` (VIRTUAL_CACHE), `CacheAccess` (Redis, Read, 1 ms), `ServiceRelation cart -> valkey-cart:6379` (DATABASE, component 7); no `CacheSlowAccess`, under the 10 ms Redis read threshold |
+| `checkout` PRODUCER `send orders` | `ServiceMeta kafka:9092` (VIRTUAL_MQ), `EndpointMeta orders`, `MQAccess` (Kafka, Produce), `MQEndpointAccess orders` (Produce), `ServiceRelation checkout -> kafka:9092` (MQ, 5 ms, component 27) |
+| `accounting` CLIENT `poll orders` | nothing: `receive` is ignored |
+| `accounting` CONSUMER `process orders` | `Service accounting`, `ServiceInstance`, `Endpoint process orders` (MQ, 9 ms), `ServiceRelation kafka:9092 -> accounting` (SERVER, VIRTUAL_MQ to GENERAL), `ServiceInstanceRelation`, `MQAccess` and `MQEndpointAccess` (Consume) |
+| `accounting` CLIENT `INSERT otel.orders` | `ServiceMeta postgresql:5432` (VIRTUAL_DATABASE), `DatabaseAccess` (PostgreSQL, 5 ms), `ServiceRelation accounting -> postgresql:5432` (DATABASE, component 22); no `DatabaseSlowStatement`, under the 200 ms default |
+
+The HTTP relation from `User` carries component 49, `http`, and the gRPC relations carry 23, `GRPC`, from the
+GENERAL peer rule's `component` map, so the topology line types read as the protocols rather than Unknown. Systems
+the map does not list fall back to `http`; adding one is a rule-file change, not a code change.
+
+#### 8.1 The rules step by step
+
+Every span goes through the same eight steps. The first happens once per resource, the rest once per span.
+
+1. **Resolve the reporting service** from the resource with `service.name`, `service.instance` and `service.layer`.
+ The layer is the explicit `service.layer` attribute if present and known, else the first matching `layer.rules`
+ entry, else GENERAL. A rule with `metrics: false` stops the analysis for every span of the resource.
+2. **Resolve attribute keys through `aliases`.** Every lookup tries the current name first, then its listed old
+ spellings. The rest of the file never sees the difference.
+3. **Dispatch on span kind.** SERVER and CONSUMER take the calling-in path, CLIENT and PRODUCER the calling-out
+ path, INTERNAL the `internal` section.
+4. **Pick the request type** by the first attribute family present in `requestType.precedence`.
+5. **Compute status, latency and endpoint name** from the `status`, `latency` and `endpoint` sections.
+6. **Find the other side.** Calling in: apply `callers`. Calling out: apply `peers.address`, then the alias cache,
+ then the `peers.virtual` list, first match wins.
+7. **Build the sources** with the shared builders, every name through `NamingControl`.
+8. **Hand them to `SourceReceiver`**, where the unchanged `core.oal` aggregates them.
+
+Three spans of the checkout trace, followed through those steps.
+
+**Span A, `cart` calls Valkey, `HGET`**
+
+```text
+resource: service.name=cart service.instance.id=cart-5f7b8c9d6-h7v2n telemetry.sdk.name=opentelemetry
+span: kind=CLIENT name=HGET 1.2 ms status={}
+ db.system.name=redis db.namespace=0 db.operation.name=HGET db.query.text="HGET ? ?"
+ server.address=valkey-cart server.port=6379 network.peer.address=10.244.3.12
+```
+
+| Step | Rule consulted | Result |
+|---|---|---|
+| 1 | `service.name.from`, `service.instance.from`, `service.layer` | `cart`, `cart-5f7b8c9d6-h7v2n`; no `service.layer`, `telemetry.sdk.name` is not `envoy`, no `faas.name`, so the `default: true` rule gives GENERAL |
+| 2 | `aliases` | `db.system.name` is present under its current name, no fallback needed |
+| 3 | kind | CLIENT, calling out |
+| 4 | `requestType.precedence` | no `gen_ai.*`, no `messaging.system`, `db.system.name` exists, so DATABASE |
+| 5 | `status`, `latency` | `status.code` UNSET, status true; 1.2 ms rounds to 1 |
+| 6 | `peers.address.from` | no `peer.service`, so `server.address` plus `server.port`, `valkey-cart:6379`; `aliasLookup` finds no SERVER span ever registered that address |
+| 6 | `peers.virtual`, first match | the VIRTUAL_CACHE rule is listed first and `redis` is in its `in` list, so the VIRTUAL_DATABASE rule below it is never reached |
+| 6 | `component.map`, `operation` of that rule | `redis` maps to `Redis`, component id 7; `HGET` is in the `read` list, so Read; `command` is `HGET` |
+| 7 | builders | `ServiceMeta{valkey-cart:6379, VIRTUAL_CACHE}`, `CacheAccess{valkey-cart:6379, type 7, latency 1, status true, Read}`, `ServiceRelation{cart -> valkey-cart:6379, CLIENT, DATABASE, component 7, latency 1}` |
+| 7 | thresholds from `TraceAnalysisConfigService` | `slowCacheReadThreshold` for `redis` is 10 ms; 1 ms is under it, no `CacheSlowAccess` |
+
+Had the same span come from an SDK two years older it would read `db.system=redis`, `db.statement="HGET ? ?"`,
+`net.peer.name=valkey-cart` and `net.peer.port=6379`. Step 2 resolves `db.system.name` through `[db.system]`,
+`server.address` through `[net.peer.name, net.host.name]` and `server.port` through `[net.peer.port, net.host.port]`,
+and steps 3 to 7 produce identical sources. That is what `aliases` is for: one virtual cache, not two.
+
+**Span B, `frontend` calls `checkout` over gRPC**
+
+```text
+resource: service.name=frontend service.instance.id=frontend-6c8d7f9b4-x2k9p
+span: kind=CLIENT name=oteldemo.CheckoutService/PlaceOrder 238.8 ms status={}
+ rpc.system=grpc rpc.service=oteldemo.CheckoutService rpc.method=PlaceOrder rpc.grpc.status_code=0
+ server.address=checkout server.port=8080 network.peer.address=10.244.2.31
+```
+
+| Step | Rule consulted | Result |
+|---|---|---|
+| 1 | layer rules | GENERAL, as for span A |
+| 3 | kind | CLIENT, calling out |
+| 4 | precedence | no GenAI, MQ or DB family; `rpc.system` exists, so RPC |
+| 5 | `status.rpcStatusCode` | `rpc.grpc.status_code` gives `"0"`; `httpResponseStatusCode` stays NONE; 239 ms |
+| 6 | `peers.address` | no `peer.service`, so `checkout:8080` |
+| 6 | `aliasLookup` | hit: the `checkout` SERVER span of this call carries `server.address=checkout`, `server.port=8080`, and `registerServerAddress: true` made it emit `NetworkAddressAliasSetup{checkout:8080 -> checkout / checkout-7d9c6b5f8-qm4tz}`; the peer resolves to the real service and instance |
+| 6 | `peers.virtual` | the peer is a real service, so the list only supplies the layer: the GENERAL rule matches on `rpc.system` |
+| 6 | GENERAL rule `component` | `rpc.system` `grpc` maps to `GRPC`, component 23 |
+| 7 | builders | `ServiceRelation{frontend -> checkout, CLIENT, RPC, latency 239, rpcStatusCode "0", component 23}`, `ServiceInstanceRelation{frontend-6c8d7f9b4-x2k9p -> checkout-7d9c6b5f8-qm4tz}` |
+
+**Span C, `accounting` consumes from Kafka, `process orders`**
+
+```text
+resource: service.name=accounting service.instance.id=accounting-8b6d4c7f5-z9q3w
+span: kind=CONSUMER name="process orders" parentSpanId=<the poll span> 9.1 ms status={}
+ messaging.system=kafka messaging.operation.type=process messaging.destination.name=orders
+ messaging.consumer.group.name=accounting server.address=kafka server.port=9092
+```
+
+| Step | Rule consulted | Result |
+|---|---|---|
+| 3 | kind | CONSUMER, calling in |
+| 4 | precedence | `messaging.system` exists and no `gen_ai.*`, so MQ |
+| 5 | `endpoint.name`, `latency` | endpoint `process orders`; 9 ms; status true |
+| 6 | `callers` | the span has a parent, so `rootSpan: User` does not apply and `remoteParent: none` would mean no caller; the VIRTUAL_MQ rule overrides this for CONSUMER spans, as the MQ branch of `parseEntry` does for agents: the caller is the broker |
+| 6 | `peers.virtual` VIRTUAL_MQ | `server.address:port` gives `kafka:9092`; `kafka` maps to `Kafka`, component 27; `consume: { kind: CONSUMER }` selects Consume; `process` is not in the `ignore` list |
+| 7 | builders | `Service{accounting, endpoint process orders, MQ, 9}`, `ServiceInstance`, `Endpoint{process orders}`, `ServiceRelation{kafka:9092 -> accounting, SERVER, VIRTUAL_MQ to GENERAL}`, `ServiceInstanceRelation`, `MQAccess{kafka:9092, Kafka, Consume}`, `MQEndpointAccess{kafka:9092, orders, Consume}`, `ServiceMeta`, `EndpointMeta` |
+
+The span before it, `poll orders`, is kind CLIENT with `messaging.operation.type` `receive`. It reaches step 6, the
+VIRTUAL_MQ rule matches on `messaging.system`, and the `ignore` list stops it: no sources. A poll is how the client
+fetched bytes, not a request anyone can be measured on.
+
+#### 8.2 What `checkout:8080` means in step 6
+
+The address in span B is not a service name. It is the key the analysis uses to find out which service answered
+there, and its meaning changes across three tiers.
+
+- **`peer.service`, the callee's declared name.** The OpenTelemetry attribute is defined as the remote side's
+ `service.name`. When present it is taken verbatim as the destination, in GENERAL, and no address is involved. No
+ instrumentation library sets it on its own; it appears only through operator configuration such as the Java
+ agent's peer-service mapping or a collector `attributes` processor, so it is absent from most spans.
+- **`server.address` plus `server.port`, the address as the agent path knows it.** Joined into `checkout:8080`, it
+ is the exact analog of the `peer` field of an agent exit span, the dialed host and port. The pod IP in
+ `network.peer.address` is deliberately not used: IPs churn and many IPs serve one service. The port is kept
+ because one host can serve several services.
+- **The alias cache, from address to service.** `checkout:8080` is looked up in `NetworkAddressAliasCache`. Entries
+ come from the other side of the hop: the `checkout` SERVER span carries `server.address=checkout` and
+ `server.port=8080`, the authority it was reached by, and `registerServerAddress: true` turns that into
+ `NetworkAddressAliasSetup{checkout:8080 -> checkout / checkout-7d9c6b5f8-qm4tz}`. For agents this registration
+ comes from `SegmentReference.networkAddressUsedAtPeer`; OTLP has no reference, so the server span's own address
+ plays the role. Both sides usually derive the string from the same Host or `:authority` header, so they match
+ unless a gateway rewrites it.
+
+When the lookup misses, the address itself becomes the destination service name in the layer the `peers.virtual`
+list picks, GENERAL for an HTTP or gRPC call, and the topology shows a node under that name, as it does for agents
+calling an uninstrumented or external peer such as `api.stripe.com:443`. A miss caused by timing heals itself:
+`ServiceTopologyBuilder` runs destinations through the alias cache again at query time, so edges recorded against
+`checkout:8080` before the server span arrived are drawn to `checkout` once the alias exists. A miss caused by
+different spellings, `checkout.default.svc.cluster.local:8080` registered against `checkout:8080` dialed, leaves an
+address-named node beside the real one; `peer.service` on the client is the cure, which is why it is the first
+tier. A CLIENT span with neither `peer.service` nor `server.address` is skipped, as an agent exit span without
+`peer` is skipped today.
+
+The alias cache is per OAP node. `NetworkAddressAliasSetup` is persisted as a `NetworkAddressAlias` record, and
+every node's `CacheUpdateTimer` reloads the recently updated records every 10 seconds, so a client span handled on
+one node sees an alias registered on another after at most that delay plus persistence. This is the same behavior
+agents get, and the query-time re-resolution above covers the gap.
+
+#### 8.3 What OAL does with the sources
+
+| Source | Metrics in `core.oal` that receive a point |
+|---|---|
+| `Service` for `accounting` | `service_cpm`, `service_resp_time` with 9, `service_sla` with true |
+| `Endpoint` `process orders` | `endpoint_cpm`, `endpoint_resp_time` |
+| `ServiceRelation` `frontend -> checkout`, CLIENT | `service_relation_client_cpm`, `service_relation_client_resp_time`; the server-side series get nothing, since no server span could name its caller |
+| `ServiceRelation` `kafka:9092 -> accounting`, SERVER | `service_relation_server_cpm`, the one server-side series that populates, because the broker is a known caller |
+| `CacheAccess` Read for `valkey-cart:6379` | `cache_read_cpm`, `cache_read_resp_time`, `cache_read_sla`, `cache_read_percentile`, and the `cache_access_*` totals |
+| `MQAccess` Consume for `kafka:9092` | `mq_service_consume_cpm`, `mq_service_consume_sla`; `mq_service_consume_latency` receives 0, since transmission latency has no source attribute |
+| `DatabaseAccess` for `postgresql:5432`, from the insert span | `database_access_cpm`, `database_access_resp_time`, `database_access_sla`, `database_access_percentile` |
+
+Two ordering rules decide most outcomes. Within `peers.virtual`, position breaks ties: Redis is a `db.system.name`
+value, so if the VIRTUAL_DATABASE rule came first every cache would be a database, and `requestType.precedence` is
+the same idea for spans carrying several attribute families. Within `aliases`, the current name comes first, so a
+span carrying both `db.system.name` and a stale `db.system` from a bridging SDK reads the current one, and upgrading
+an SDK never flips an entity's identity.
+
+### 9. Gaps compared with agent traces
+
+The agent path is the reference. Everything below is a place where OTLP spans give less, or different, and the
+design either compensates, documents, or offers an opt-in.
+
+Gaps that follow from data the wire does not carry, and no rule can close:
+
+| Gap | Agent path | OTLP path | Consequence |
+|---|---|---|---|
+| Caller identity on the server side | `SegmentReference` names the parent service, instance, endpoint and the dialed address | `parentSpanId` only | `service_relation_server_*` populate only for `User`, gateways and brokers; edges carry client-observed numbers only |
+| Endpoint-level dependency | `EndpointRelation` from the parent endpoint; `EndpointDepFromCrossThreadAnalysisListener` relates endpoints across async hops | no parent endpoint; INTERNAL spans emit nothing | `endpoint_relation_*` exist only from `User`; the endpoint dependency view is empty |
+| Gateway detection on the server side | the address the client dialed, matched against `gateways.yml` | `client.address`, the source IP | matches only when the gateway's egress IPs are configured |
+| Message transmission latency | `transmission.latency`, the producer timestamp propagated in headers | nothing in the messaging conventions | `mq_service_consume_latency` reads 0 |
+| Cache operation and key | `cache.op`, `cache.cmd`, `cache.key` | Read or Write classified from `db.operation.name` by a command table; no key attribute exists | `CacheSlowAccess.key` is empty; commands outside the table are `Others` |
+
+Gaps whose size depends on how each SDK was instrumented:
+
+| Gap | Agent path | OTLP path | Consequence |
+|---|---|---|---|
+| Alias matching | the server registers the exact address the client dialed | the server registers its own `server.address`, defined as the Host or `:authority` header, but some SDKs fill it with the listening hostname | a mismatch leaves an address-named node beside the real one; `peer.service` is the cure |
+| Endpoint names | plugins normalize operation names from the framework's route | `{method} {route}` when the framework reports `http.route`, bare `GET` when it does not, arbitrary names from manual instrumentation | one endpoint absorbing every request, or a cardinality explosion; `endpoint-name-grouping.yml` repairs, it does not source |
+| Error semantics | each plugin decides `isError` from exceptions and status codes | `STATUS_CODE_ERROR` for server 5xx and client 4xx and 5xx by convention, often UNSET | `service_sla` of an agent service and an SDK service are not comparable |
+| Component identity | Tomcat, Spring MVC, Dubbo, the JDBC driver, Jedis | `grpc`, `http`, `postgresql`, `kafka` | coarser topology icons; no component-based server-name inference |
+| Instance identity | the agent's instance name, unique per process | `service.instance.id` is optional | without it and without a pod or host name, every process is the instance `unknown`; instance metrics are wrong rather than missing |
+| Sampling | every segment reported by default, OAP samples for storage | head sampling in the SDK is common | dropped spans are requests the metrics never see; MESH defaults to no metrics for this reason |
+
+One correctness risk the agent path does not have: duplicate delivery from exporter retries, handled by the seen-set
+in [section 6](#6-the-analysis-span-by-span) within one node, and not across nodes.
+
+Where OTLP is better: the reporting service's layer is a per-resource decision, where agents only ever produce
+GENERAL or FAAS; resource attributes carry instance properties agents report only partially; and the semantic
+conventions give typed, standardized attributes for status codes, database systems and messaging systems rather
+than per-plugin tag names.
+
+Mitigations, in and out of scope:
+
+- The seen-set for retried spans, in scope.
+- Caller identity through request attributes, opt-in through `callers.fromAttributes`. An SDK extension or a
+ collector processor stamps the caller's service, instance and endpoint into W3C Baggage and copies them onto the
+ server span; the rule then names the caller and the server-side and endpoint relations return for that fleet. It
+ is not a standard convention, so it ships disabled.
+- `peer.service` for address mismatches and `http.route` support for useful endpoint names, documented as the two
+ instrumentation prerequisites in the operator doc.
+- A dry run on the admin server, `POST /debugging/otlp-trace-analysis`, which takes an OTLP/JSON payload and returns
+ the sources the current rules would emit without emitting them, so an operator can see these gaps against real
+ data before trusting the metrics.
+
+### 10. Self-observability
+
+Two counters and a histogram on the receiver's telemetry, next to `otel_spans_latency` and `otel_spans_dropped`:
+`otlp_trace_analysis_spans` labeled by kind and resolved layer, `otlp_trace_analysis_skipped` labeled by reason, one
+of `no_service_name`, `no_peer`, `unknown_kind`, `layer_metrics_disabled`, `ignored_operation`, and
+`otlp_trace_analysis_latency` for the per-span rule evaluation, which is the number to watch when a rule file grows.
+A fourth counter, `otlp_trace_analysis_duplicates`, counts spans the seen-set rejected; a non-zero rate is the sign of
+an exporter retrying against a slow OAP.
+
+### 11. Tests
+
+- Unit tests for the rules engine: alias fallback, request-type precedence, layer resolution including an unknown
+ `service.layer`, the MESH `peer` and `instance` regexes over subset and non-subset cluster names, the virtual-peer
+ order for Redis, the caller rules for root, remote-parent and gateway spans, `callers.fromAttributes` with and
+ without the attributes present, and the seen-set: the same span twice within the window emits sources once, and
+ again after the window.
+- Listener tests over two fixture payloads checked in as JSON: the demo checkout trace above and an Istio Bookinfo
+ hop with two sidecar resources and an application resource. The expected `Source` objects are asserted field by
+ field, including entity ids and time buckets.
+- The `otlp-traces` e2e runs with `SW_OTEL_TRACE_ANALYSIS=true` on BanyanDB and verifies with `swctl` that the demo
+ services appear under `service ly GENERAL`, that `metrics exec` returns `service_cpm` and `service_resp_time` for
+ them, that `dependency service` shows the `frontend -> checkout -> cart` edges and the virtual nodes, that
+ `service ly VIRTUAL_DATABASE`, `VIRTUAL_CACHE` and `VIRTUAL_MQ` list the peers, and that `database_access_resp_time`
+ is present. `test/e2e-v2/cases/storage/expected/config-dump.yml` gains the two new defaults.
+- `otlp-virtual-genai` runs with the flag on to prove the GenAI listener and this listener coexist on the same spans.
+
+### 12. Documentation
+
+`docs/en/setup/backend/otlp-trace.md` gains a section on metrics from OTLP traces: the two settings, how the layer
+is decided, the rule file with its sections explained, the list of what appears in the UI and what does not,
+the sampling caveat, and the semantic-convention versions the shipped aliases cover. `docs/en/changes/changes.md`
+records the feature. No new menu entry is needed, since the entities land in the existing General and virtual
+layers.
+
+## Imported Dependencies libs and their licenses
+
+None.
+
+## Compatibility
+
+- `otlpTraceAnalysis` defaults to `false`. Existing deployments see no new entities, metrics or sources.
+- `OTLPSpanReader` gains default methods only. `AnalyzerModule.services()` gains one service with one provider.
+ Moving the two source builders to `server-core` changes packages and visibility, not behavior.
+- It works with both `otlpTraceStorage` modes and does not depend on the native storage proposal landing first.
+ The two proposals share the `OTLPSpanReader.attributes()` addition and the phase-one placement.
+- `service.namespace` is not part of the service name unless `service.name.group` is enabled, so two services
+ with the same `service.name` in different namespaces are one entity by default, as they would be for agents
+ without the `group::name` convention. Enabling the group changes every name to `<namespace>::<name>` and must be
+ matched by `peer.service` values; it is a deployment-wide decision.
+- An OTLP service and an agent service with the same name in the same layer are one entity, because the id is the
+ name plus the layer. That is intended: a service migrating from an agent to an SDK keeps its history. A process
+ running both an agent and an SDK at once would count its requests twice; this is documented, not prevented.
+- Server-side relation metrics populate only for `User`, gateway and broker callers, and endpoint relations only
+ from `User`, unless `callers.fromAttributes` is enabled fleet-wide. The full comparison with agent traces is in
+ [section 9](#9-gaps-compared-with-agent-traces).
+- Retried exporter batches are deduplicated per OAP node within `otlpTraceAnalysisDedupWindow`; a retry that lands
+ on another node still counts twice.
+- Metrics are exact only if OAP sees every span. SkyWalking agents report every segment and let OAP sample;
+ OpenTelemetry SDKs often sample at the head. For exact numbers the SDK must export at 100 percent and
+ `otlpTraceSampleRate` in `receiver-otel` should carry the storage sampling. MESH metrics stay off by default for
+ this reason, since Istio samples at one percent.
+- A GENERAL service created from OTLP spans shows metrics and topology in the existing dashboards. Its trace tab
+ queries native segments and is empty until the Horizon UI learns to fetch that service's traces from the Zipkin
+ or `/otlp` TraceQL datasource, whichever store the deployment uses. This is a UI change outside this proposal.
+- Spans that arrive over the Zipkin protocol have no resource attributes and are not analyzed by this listener.
+ A phase-two counterpart could be added later; it is out of scope here.
+
+## General usage docs
+
+Enable the analysis and, if needed, adjust the rules:
+
+```yaml
+receiver-otel:
+ selector: default
+ default:
+ enabledHandlers: otlp-traces,otlp-metrics,otlp-logs
+ otlpTraceAnalysis: true
+ otlpTraceAnalysisRules: otlp-trace-analysis.yml
+```
+
+After an OpenTelemetry SDK exports traces, its services appear under the General layer with the standard service,
+instance and endpoint dashboards, the topology shows the client-side edges between them, and databases, caches and
+brokers they call appear as virtual services with their access metrics. Alarm rules written against `service_*`,
+`endpoint_*`, `service_relation_*` and the virtual-service metrics fire for them without change, since the metrics
+are the same. To place a group of services in another layer, set `service.layer` on their resource, for example
+through the collector:
+
+```yaml
+processors:
+ resource/layer:
+ attributes:
+ - key: service.layer
+ value: FAAS
+ action: upsert
+```
+
+To recognize an SDK that still emits an old attribute name, add it to `aliases`. To make a new database or broker
+show its own icon, add its `db.system.name` or `messaging.system` value to the matching `component.map` with a name
+from `component-libraries.yml`. To let mesh spans produce metrics where ALS is not deployed, set `metrics: true` on
+the MESH rule.
diff --git a/docs/menu.yml b/docs/menu.yml
index 4a7d289fc3..f8a6592623 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -254,6 +254,8 @@ catalog:
path: "/en/setup/backend/zipkin-trace"
- name: "OpenTelemetry Trace"
path: "/en/setup/backend/otlp-trace"
+ - name: "OpenTelemetry Trace Analysis"
+ path: "/en/setup/backend/trace-analyzer"
- name: "Metrics"
catalog:
- name: "OAL Scripts"
@@ -390,6 +392,8 @@ catalog:
path: "/en/concepts-and-designs/mal"
- name: "Analysis Logs"
path: "/en/concepts-and-designs/lal"
+ - name: "Analysis OpenTelemetry Traces"
+ path: "/en/concepts-and-designs/tal"
- name: "Runtime Rule Hot-Update"
path: "/en/concepts-and-designs/runtime-rule-hot-update"
- name: "Profiling"
diff --git a/oap-server/analyzer/agent-analyzer/src/main/java/org/apache/skywalking/oap/server/analyzer/provider/trace/parser/listener/DatabaseSlowStatementBuilder.java b/oap-server/analyzer/agent-analyzer/src/main/java/org/apache/skywalking/oap/server/analyzer/provider/trace/parser/listener/DatabaseSlowStatementBuilder.java
index 178acb69b1..ced9f1cd39 100644
--- a/oap-server/analyzer/agent-analyzer/src/main/java/org/apache/skywalking/oap/server/analyzer/provider/trace/parser/listener/DatabaseSlowStatementBuilder.java
+++ b/oap-server/analyzer/agent-analyzer/src/main/java/org/apache/skywalking/oap/server/analyzer/provider/trace/parser/listener/DatabaseSlowStatementBuilder.java
@@ -32,10 +32,13 @@ import org.apache.skywalking.oap.server.core.source.DatabaseSlowStatement;
import org.apache.skywalking.oap.server.core.source.LALOutputBuilder;
import org.apache.skywalking.oap.server.core.source.LogMetadata;
import org.apache.skywalking.oap.server.core.source.SourceReceiver;
+import org.apache.skywalking.oap.server.core.source.TALOutputBuilder;
+import org.apache.skywalking.oap.server.core.trace.SpanMetadata;
import org.apache.skywalking.oap.server.library.module.ModuleManager;
+import org.apache.skywalking.oap.server.library.util.StringUtil;
@Slf4j
-public class DatabaseSlowStatementBuilder implements LALOutputBuilder {
+public class DatabaseSlowStatementBuilder implements LALOutputBuilder, TALOutputBuilder {
public static final String NAME = "SlowSQL";
private static NamingControl NAMING_CONTROL;
@@ -85,12 +88,7 @@ public class DatabaseSlowStatementBuilder implements LALOutputBuilder {
@Override
public void init(final LogMetadata metadata, final Object input,
final ModuleManager moduleManager) {
- if (!INITIALIZED) {
- NAMING_CONTROL = moduleManager.find(CoreModule.NAME)
- .provider()
- .getService(NamingControl.class);
- INITIALIZED = true;
- }
+ ensureNamingControl(moduleManager);
// Only populate fields not already set by the LAL extractor.
if (this.serviceName == null) {
this.serviceName = metadata.getService();
@@ -111,6 +109,42 @@ public class DatabaseSlowStatementBuilder implements LALOutputBuilder {
}
}
+ /**
+ * The span-side lifecycle. The standard fields come from {@code meta}, which carries whatever the rule's
+ * extractor overwrote, so a TAL rule names the database with {@code service peer} and the layer with
+ * {@code layer "OTLP_VIRTUAL_DATABASE"} exactly as a LAL slow-SQL rule names its own.
+ *
+ * @param meta the span's metadata view
+ * @param input the wire span, unread by this builder
+ * @param moduleManager for resolving {@code NamingControl} on the first record
+ */
+ @Override
+ public void init(final SpanMetadata meta, final Object input, final ModuleManager moduleManager) {
+ ensureNamingControl(moduleManager);
+ if (this.serviceName == null) {
+ this.serviceName = meta.getService();
+ }
+ if (StringUtil.isNotEmpty(meta.getLayer())) {
+ // A span's layer is a string until here; an unknown name leaves the default rather than failing the
+ // record, since the id it builds only depends on the layer's normal flag. Layer.nameOf would answer
+ // UNDEFINED for it instead, silently.
+ try {
+ this.layer = Layer.valueOf(meta.getLayer());
+ } catch (final IllegalArgumentException e) {
+ log.warn("SlowSQL record names an unknown layer '{}', keeping {}", meta.getLayer(), this.layer);
+ }
+ }
+ if (this.traceId == null) {
+ this.traceId = meta.getTraceId();
+ }
+ if (this.timestamp == 0) {
+ this.timestamp = meta.getTimestamp();
+ }
+ if (this.timeBucket == 0) {
+ this.timeBucket = TimeBucket.getTimeBucket(this.timestamp, DownSampling.Second);
+ }
+ }
+
@Override
public void complete(final SourceReceiver sourceReceiver) {
if (id == null || latency < 1 || statement == null) {
@@ -128,6 +162,15 @@ public class DatabaseSlowStatementBuilder implements LALOutputBuilder {
sourceReceiver.receive(toDatabaseSlowStatement());
}
+ private static void ensureNamingControl(final ModuleManager moduleManager) {
+ if (!INITIALIZED) {
+ NAMING_CONTROL = moduleManager.find(CoreModule.NAME)
+ .provider()
+ .getService(NamingControl.class);
+ INITIALIZED = true;
+ }
+ }
+
public void prepare() {
this.serviceName = NAMING_CONTROL.formatServiceName(serviceName);
}
diff --git a/oap-server/analyzer/agent-analyzer/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.core.source.TALOutputBuilder b/oap-server/analyzer/agent-analyzer/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.core.source.TALOutputBuilder
new file mode 100644
index 0000000000..8e5fbd6b06
--- /dev/null
+++ b/oap-server/analyzer/agent-analyzer/src/main/resources/META-INF/services/org.apache.skywalking.oap.server.core.source.TALOutputBuilder
@@ -0,0 +1,19 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+
+org.apache.skywalking.oap.server.analyzer.provider.trace.parser.listener.DatabaseSlowStatementBuilder
diff --git a/oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/v2/Analyzer.java b/oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/v2/Analyzer.java
index 6638408398..3dec9ec273 100644
--- a/oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/v2/Analyzer.java
+++ b/oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/v2/Analyzer.java
@@ -21,7 +21,6 @@ package org.apache.skywalking.oap.meter.analyzer.v2;
import org.apache.skywalking.oap.server.core.dsl.DslSourceRef;
import com.google.common.base.Strings;
import com.google.common.collect.ImmutableMap;
-import com.google.gson.JsonObject;
import io.vavr.Tuple;
import io.vavr.Tuple2;
import java.util.List;
@@ -45,18 +44,9 @@ import org.apache.skywalking.oap.meter.analyzer.v2.dsl.Result;
import org.apache.skywalking.oap.meter.analyzer.v2.dsl.Sample;
import org.apache.skywalking.oap.meter.analyzer.v2.dsl.SampleFamily;
import org.apache.skywalking.oap.meter.analyzer.v2.dsl.debug.MALDebug;
-import org.apache.skywalking.oap.server.core.analysis.Layer;
import org.apache.skywalking.oap.server.core.analysis.TimeBucket;
import org.apache.skywalking.oap.server.core.dsl.debug.GateHolder;
-import org.apache.skywalking.oap.server.core.analysis.manual.endpoint.EndpointTraffic;
-import org.apache.skywalking.oap.server.core.analysis.manual.instance.InstanceTraffic;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.instance.ServiceInstanceRelationClientSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.instance.ServiceInstanceRelationServerSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.process.ProcessRelationClientSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.process.ProcessRelationServerSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.service.ServiceRelationClientSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.relation.service.ServiceRelationServerSideMetrics;
-import org.apache.skywalking.oap.server.core.analysis.manual.service.ServiceTraffic;
+import org.apache.skywalking.oap.server.core.analysis.meter.EntityTrafficGenerator;
import org.apache.skywalking.oap.server.core.analysis.meter.MeterEntity;
import org.apache.skywalking.oap.server.core.analysis.meter.MeterSystem;
import org.apache.skywalking.oap.server.core.storage.model.StorageManipulationOpt;
@@ -66,10 +56,8 @@ import org.apache.skywalking.oap.server.core.analysis.meter.function.BucketedVal
import org.apache.skywalking.oap.server.core.analysis.meter.function.PercentileArgument;
import org.apache.skywalking.oap.server.core.analysis.metrics.DataLabel;
import org.apache.skywalking.oap.server.core.analysis.metrics.DataTable;
-import org.apache.skywalking.oap.server.core.analysis.worker.MetricsStreamProcessor;
import static com.google.common.collect.ImmutableMap.toImmutableMap;
-import static java.util.Objects.requireNonNull;
import static java.util.stream.Collectors.groupingBy;
import static java.util.stream.Collectors.mapping;
import static java.util.stream.Collectors.toList;
@@ -336,7 +324,7 @@ public class Analyzer {
// A separate scope record would carry only the metric type ("single"/"labeled"/…),
// which is internal classification, not anything the operator authored.
meterSamples.forEach((meterEntity, ss) -> {
- generateTraffic(meterEntity);
+ EntityTrafficGenerator.generate(meterEntity);
switch (metricType) {
case single:
AcceptableValue<Long> sv = meterSystem.buildMetrics(metricName, Long.class);
@@ -510,160 +498,4 @@ public class Analyzer {
v.setTimeBucket(TimeBucket.getMinuteTimeBucket(time));
meterSystem.doStreamingCalculation(v);
}
-
- private void generateTraffic(MeterEntity entity) {
- if (entity.getDetectPoint() != null) {
- switch (entity.getScopeType()) {
- case SERVICE_RELATION:
- serviceRelationTraffic(entity);
- break;
- case PROCESS_RELATION:
- processRelationTraffic(entity);
- break;
- case SERVICE_INSTANCE_RELATION:
- serviceInstanceRelationTraffic(entity);
- break;
- default:
- }
- } else {
- toService(requireNonNull(entity.getServiceName()), entity.getLayer());
- }
-
- if (!com.google.common.base.Strings.isNullOrEmpty(entity.getInstanceName())) {
- InstanceTraffic instanceTraffic = new InstanceTraffic();
- instanceTraffic.setName(entity.getInstanceName());
- instanceTraffic.setServiceId(entity.serviceId());
- instanceTraffic.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- instanceTraffic.setLastPingTimestamp(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- if (entity.getInstanceProperties() != null && !entity.getInstanceProperties().isEmpty()) {
- final JsonObject properties = new JsonObject();
- entity.getInstanceProperties().forEach((k, v) -> properties.addProperty(k, v));
- instanceTraffic.setProperties(properties);
- }
- MetricsStreamProcessor.getInstance().in(instanceTraffic);
- }
- if (!com.google.common.base.Strings.isNullOrEmpty(entity.getEndpointName())) {
- EndpointTraffic endpointTraffic = new EndpointTraffic();
- endpointTraffic.setName(entity.getEndpointName());
- endpointTraffic.setServiceId(entity.serviceId());
- endpointTraffic.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- endpointTraffic.setLastPingTimestamp(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- MetricsStreamProcessor.getInstance().in(endpointTraffic);
- }
- }
-
- private void toService(String serviceName, Layer layer) {
- ServiceTraffic s = new ServiceTraffic();
- s.setName(requireNonNull(serviceName));
- s.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- s.setLayer(layer);
- MetricsStreamProcessor.getInstance().in(s);
- }
-
- private void serviceRelationTraffic(MeterEntity entity) {
- switch (entity.getDetectPoint()) {
- case SERVER:
- entity.setServiceName(entity.getDestServiceName());
- toService(requireNonNull(entity.getDestServiceName()), entity.getLayer());
- serviceRelationServerSide(entity);
- break;
- case CLIENT:
- entity.setServiceName(entity.getSourceServiceName());
- toService(requireNonNull(entity.getSourceServiceName()), entity.getLayer());
- serviceRelationClientSide(entity);
- break;
- default:
- }
- }
-
- private void serviceRelationServerSide(MeterEntity entity) {
- ServiceRelationServerSideMetrics metrics = new ServiceRelationServerSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setSourceServiceId(entity.sourceServiceId());
- metrics.setDestServiceId(entity.destServiceId());
- metrics.getComponentIds().add(entity.getComponentId());
- metrics.setEntityId(entity.id());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
- private void serviceRelationClientSide(MeterEntity entity) {
- ServiceRelationClientSideMetrics metrics = new ServiceRelationClientSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setSourceServiceId(entity.sourceServiceId());
- metrics.setDestServiceId(entity.destServiceId());
- metrics.getComponentIds().add(entity.getComponentId());
- metrics.setEntityId(entity.id());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
- private void processRelationTraffic(MeterEntity entity) {
- switch (entity.getDetectPoint()) {
- case SERVER:
- processRelationServerSide(entity);
- break;
- case CLIENT:
- processRelationClientSide(entity);
- break;
- default:
- }
- }
-
- private void processRelationServerSide(MeterEntity entity) {
- ProcessRelationServerSideMetrics metrics = new ProcessRelationServerSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setServiceInstanceId(entity.serviceInstanceId());
- metrics.setSourceProcessId(entity.getSourceProcessId());
- metrics.setDestProcessId(entity.getDestProcessId());
- metrics.setEntityId(entity.id());
- metrics.setComponentId(entity.getComponentId());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
- private void processRelationClientSide(MeterEntity entity) {
- ProcessRelationClientSideMetrics metrics = new ProcessRelationClientSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setServiceInstanceId(entity.serviceInstanceId());
- metrics.setSourceProcessId(entity.getSourceProcessId());
- metrics.setDestProcessId(entity.getDestProcessId());
- metrics.setEntityId(entity.id());
- metrics.setComponentId(entity.getComponentId());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
- private void serviceInstanceRelationTraffic(MeterEntity entity) {
- switch (entity.getDetectPoint()) {
- case SERVER:
- toService(requireNonNull(entity.getDestServiceName()), entity.getLayer());
- serviceInstanceRelationServerSide(entity);
- break;
- case CLIENT:
- toService(requireNonNull(entity.getSourceServiceName()), entity.getLayer());
- serviceInstanceRelationClientSide(entity);
- break;
- default:
- }
- }
-
- private void serviceInstanceRelationServerSide(MeterEntity entity) {
- ServiceInstanceRelationServerSideMetrics metrics = new ServiceInstanceRelationServerSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setSourceServiceId(entity.sourceServiceId());
- metrics.setSourceServiceInstanceId(entity.sourceServiceInstanceId());
- metrics.setDestServiceId(entity.destServiceId());
- metrics.setDestServiceInstanceId(entity.destServiceInstanceId());
- metrics.setEntityId(entity.id());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
- private void serviceInstanceRelationClientSide(MeterEntity entity) {
- ServiceInstanceRelationClientSideMetrics metrics = new ServiceInstanceRelationClientSideMetrics();
- metrics.setTimeBucket(TimeBucket.getMinuteTimeBucket(System.currentTimeMillis()));
- metrics.setSourceServiceId(entity.sourceServiceId());
- metrics.setSourceServiceInstanceId(entity.sourceServiceInstanceId());
- metrics.setDestServiceId(entity.destServiceId());
- metrics.setDestServiceInstanceId(entity.destServiceInstanceId());
- metrics.setEntityId(entity.id());
- MetricsStreamProcessor.getInstance().in(metrics);
- }
-
}
diff --git a/oap-server/analyzer/pom.xml b/oap-server/analyzer/pom.xml
index 9ba60b726c..3aedb69299 100644
--- a/oap-server/analyzer/pom.xml
+++ b/oap-server/analyzer/pom.xml
@@ -33,6 +33,7 @@
<module>event-analyzer</module>
<module>meter-analyzer</module>
<module>log-analyzer</module>
+ <module>trace-analyzer</module>
<module>hierarchy</module>
<module>gen-ai-analyzer</module>
<module>ai-evaluation</module>
diff --git a/oap-server/server-receiver-plugin/otel-receiver-plugin/pom.xml b/oap-server/analyzer/trace-analyzer/pom.xml
similarity index 60%
copy from oap-server/server-receiver-plugin/otel-receiver-plugin/pom.xml
copy to oap-server/analyzer/trace-analyzer/pom.xml
index 47a03c0491..174c1ebc50 100644
--- a/oap-server/server-receiver-plugin/otel-receiver-plugin/pom.xml
+++ b/oap-server/analyzer/trace-analyzer/pom.xml
@@ -14,45 +14,70 @@
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
- ~
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
- <artifactId>server-receiver-plugin</artifactId>
+ <artifactId>analyzer</artifactId>
<groupId>org.apache.skywalking</groupId>
<version>${revision}</version>
</parent>
<modelVersion>4.0.0</modelVersion>
- <artifactId>otel-receiver-plugin</artifactId>
- <packaging>jar</packaging>
+ <artifactId>trace-analyzer</artifactId>
<dependencies>
<dependency>
<groupId>org.apache.skywalking</groupId>
- <artifactId>receiver-proto</artifactId>
+ <artifactId>server-core</artifactId>
<version>${project.version}</version>
</dependency>
+ <!-- The OTLP Span proto is the default `span` root a rule reads, resolved by reflection at compile. -->
<dependency>
<groupId>org.apache.skywalking</groupId>
- <artifactId>skywalking-sharing-server-plugin</artifactId>
+ <artifactId>receiver-proto</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
- <groupId>org.apache.skywalking</groupId>
- <artifactId>meter-analyzer</artifactId>
- <version>${project.version}</version>
+ <groupId>com.google.code.gson</groupId>
+ <artifactId>gson</artifactId>
+ <version>${gson.version}</version>
</dependency>
<dependency>
<groupId>org.apache.skywalking</groupId>
- <artifactId>log-analyzer</artifactId>
+ <artifactId>configuration-api</artifactId>
<version>${project.version}</version>
</dependency>
+ <dependency>
+ <groupId>org.antlr</groupId>
+ <artifactId>antlr4-runtime</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.javassist</groupId>
+ <artifactId>javassist</artifactId>
+ </dependency>
<dependency>
<groupId>org.apache.skywalking</groupId>
- <artifactId>zipkin-receiver-plugin</artifactId>
+ <artifactId>server-testing</artifactId>
<version>${project.version}</version>
+ <scope>test</scope>
</dependency>
</dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.antlr</groupId>
+ <artifactId>antlr4-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>antlr</id>
+ <goals>
+ <goal>antlr4</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
</project>
diff --git a/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALLexer.g4 b/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALLexer.g4
new file mode 100644
index 0000000000..9282b08583
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALLexer.g4
@@ -0,0 +1,174 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+// Trace Analysis Language lexer
+lexer grammar TALLexer;
+
+@Header {package org.apache.skywalking.tal.rt.grammar;}
+
+// Keywords - block structure
+FILTER: 'filter';
+EXTRACTOR: 'extractor';
+SINK: 'sink';
+PERSIST: 'persist';
+ABORT: 'abort';
+
+// Keywords - extractor statements
+SERVICE: 'service';
+INSTANCE: 'instance';
+ENDPOINT: 'endpoint';
+LAYER: 'layer';
+TAG: 'tag';
+METRICS: 'metrics';
+ALIAS: 'alias';
+
+// Keywords - metrics block
+NAME: 'name';
+SCOPE: 'scope';
+FUNCTION: 'function';
+VALUE: 'value';
+MATCH: 'match';
+STATUS: 'status';
+LABELS: 'labels';
+BUCKETS: 'buckets';
+RANKS: 'ranks';
+TIMESTAMP: 'timestamp';
+
+// Keywords - relation detect points, written bare as an entity constructor's first argument
+CLIENT: 'CLIENT';
+SERVER: 'SERVER';
+
+// Keywords - sink and persist statements
+SAMPLER: 'sampler';
+RATE_LIMIT: 'rateLimit';
+RPM: 'rpm';
+ENFORCER: 'enforcer';
+DROPPER: 'dropper';
+
+// Keywords - local variables
+DEF: 'def';
+
+// Keywords - control flow
+IF: 'if';
+ELSE: 'else';
+
+// Keywords - type cast
+AS: 'as';
+STRING_TYPE: 'String';
+LONG_TYPE: 'Long';
+INTEGER_TYPE: 'Integer';
+DOUBLE_TYPE: 'Double';
+FLOAT_TYPE: 'Float';
+BOOLEAN_TYPE: 'Boolean';
+
+// Keywords - built-in roots
+SPAN: 'span';
+META: 'meta';
+
+// Comparison and logical operators
+DEQ: '==';
+NEQ: '!=';
+AND: '&&';
+OR: '||';
+NOT: '!';
+GT: '>';
+LT: '<';
+GTE: '>=';
+LTE: '<=';
+
+// Delimiters
+DOT: '.';
+COMMA: ',';
+COLON: ':';
+SEMI: ';';
+L_PAREN: '(';
+R_PAREN: ')';
+L_BRACE: '{';
+R_BRACE: '}';
+L_BRACKET: '[';
+R_BRACKET: ']';
+QUESTION: '?';
+ASSIGN: '=';
+
+// Arithmetic
+PLUS: '+';
+MINUS: '-';
+STAR: '*';
+SLASH: '/';
+
+// Literals
+TRUE: 'true';
+FALSE: 'false';
+NULL: 'null';
+
+// Numeric literal. Suffix rules mirror Java:
+// * `L` / `l` is valid only on integer literals (no decimal, no exponent).
+// * `F` / `f` and `D` / `d` are valid on any form.
+// Bare integer literals are int if they fit, otherwise long; bare decimal/exponent literals
+// are double unless suffixed.
+NUMBER
+ : Digit+ '.' Digit+ ([eE] [+\-]? Digit+)? [FfDd]?
+ | Digit+ [eE] [+\-]? Digit+ [FfDd]?
+ | '.' Digit+ ([eE] [+\-]? Digit+)? [FfDd]?
+ | Digit+ [LlFfDd]?
+ ;
+
+// String literal: single or double quoted
+STRING
+ : '\'' (~['\\\r\n] | EscapeSequence)* '\''
+ | '"' (~["\\\r\n] | EscapeSequence)* '"'
+ ;
+
+// Comments
+LINE_COMMENT
+ : '//' ~[\r\n]* -> channel(HIDDEN)
+ ;
+
+BLOCK_COMMENT
+ : '/*' .*? '*/' -> channel(HIDDEN)
+ ;
+
+// Whitespace
+WS
+ : [ \t\r\n]+ -> channel(HIDDEN)
+ ;
+
+// Identifiers
+IDENTIFIER
+ : Letter LetterOrDigit*
+ ;
+
+// Fragments
+fragment EscapeSequence
+ : '\\' [btnfr"'\\]
+ | '\\' ([0-3]? [0-7])? [0-7]
+ | '\\' .
+ ;
+
+fragment Digit
+ : [0-9]
+ ;
+
+fragment Letter
+ : [a-zA-Z_]
+ ;
+
+fragment LetterOrDigit
+ : Letter
+ | [0-9]
+ ;
diff --git a/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALParser.g4 b/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALParser.g4
new file mode 100644
index 0000000000..16c3007896
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/antlr4/org/apache/skywalking/tal/rt/grammar/TALParser.g4
@@ -0,0 +1,424 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+// Trace Analysis Language parser
+//
+// Covers TAL DSL patterns:
+// filter { extractor {} sink {} persist {} }
+// if (meta.kind == "SERVER") { ... }
+// extractor { layer "OTEL_SERVICE"; def svc = service(meta.service, meta.layer) }
+// metrics { name "service_cpm"; scope svc; function cpm; value 1 }
+// metrics { name "service_percentile"; scope svc; function percentile; value meta.latency
+// buckets [10, 25, 50] }
+// sink { sampler { rateLimit("id") { rpm 6000 } } }
+// persist { enforcer {} }
+parser grammar TALParser;
+
+@Header {package org.apache.skywalking.tal.rt.grammar;}
+
+options { tokenVocab=TALLexer; }
+
+// ==================== Top-level ====================
+
+root
+ : filterBlock EOF
+ ;
+
+// ==================== Filter block ====================
+
+filterBlock
+ : FILTER L_BRACE filterContent R_BRACE
+ ;
+
+// SEMI is an optional separator everywhere, so a `metrics {}` block fits on one line.
+filterContent
+ : (filterStatement | SEMI)*
+ ;
+
+filterStatement
+ : extractorBlock
+ | sinkBlock
+ | persistBlock
+ | ifStatement
+ | abortBlock
+ | defStatement
+ | aliasStatement
+ ;
+
+abortBlock
+ : ABORT L_BRACE R_BRACE
+ ;
+
+// ==================== Extractor block ====================
+
+extractorBlock
+ : EXTRACTOR L_BRACE extractorContent R_BRACE
+ ;
+
+extractorContent
+ : (extractorStatement | SEMI)*
+ ;
+
+extractorStatement
+ : defStatement
+ | serviceStatement
+ | instanceStatement
+ | endpointStatement
+ | layerStatement
+ | tagStatement
+ | aliasStatement
+ | metricsBlock
+ | ifStatement
+ | abortBlock
+ | outputFieldStatement
+ ;
+
+defStatement
+ : DEF IDENTIFIER ASSIGN valueAccess typeCast?
+ ;
+
+serviceStatement
+ : SERVICE valueAccess typeCast?
+ ;
+
+instanceStatement
+ : INSTANCE valueAccess typeCast?
+ ;
+
+endpointStatement
+ : ENDPOINT valueAccess typeCast?
+ ;
+
+layerStatement
+ : LAYER valueAccess typeCast?
+ ;
+
+outputFieldStatement
+ : anyIdentifier valueAccess typeCast?
+ ;
+
+tagStatement
+ : TAG tagMap
+ | TAG STRING COLON valueAccess typeCast?
+ ;
+
+tagMap
+ : anyIdentifier COLON valueAccess typeCast? (COMMA anyIdentifier COLON valueAccess typeCast?)*
+ ;
+
+// `alias <address>` registers the address this span was dialed at as an alias of meta.service, the row a
+// later CLIENT span's resolveAlias(peer) reads to land its edge on this service instead of an address-named node.
+aliasStatement
+ : ALIAS valueAccess typeCast?
+ ;
+
+// ==================== Metrics block ====================
+
+metricsBlock
+ : METRICS L_BRACE metricsContent R_BRACE
+ ;
+
+metricsContent
+ : (metricsStatement | SEMI)*
+ ;
+
+metricsStatement
+ : metricsNameStatement
+ | metricsScopeStatement
+ | metricsFunctionStatement
+ | metricsValueStatement
+ | metricsMatchStatement
+ | metricsStatusStatement
+ | metricsLabelsStatement
+ | metricsBucketsStatement
+ | metricsRanksStatement
+ | metricsTimestampStatement
+ ;
+
+metricsNameStatement
+ : NAME valueAccess typeCast?
+ ;
+
+// The entity the value lands on: an entity constructor, or a def variable holding one.
+metricsScopeStatement
+ : SCOPE valueAccess
+ ;
+
+metricsFunctionStatement
+ : FUNCTION anyIdentifier
+ ;
+
+metricsValueStatement
+ : VALUE valueAccess typeCast?
+ ;
+
+// `percent` counts a span as a match when this holds.
+metricsMatchStatement
+ : MATCH condition
+ ;
+
+// `apdex` counts a span as successful when this holds.
+metricsStatusStatement
+ : STATUS condition
+ ;
+
+metricsLabelsStatement
+ : LABELS labelMap
+ ;
+
+labelMap
+ : labelEntry (COMMA labelEntry)*
+ ;
+
+labelEntry
+ : anyIdentifier COLON valueAccess typeCast?
+ ;
+
+metricsBucketsStatement
+ : BUCKETS numberList
+ ;
+
+metricsRanksStatement
+ : RANKS numberList
+ ;
+
+metricsTimestampStatement
+ : TIMESTAMP valueAccess typeCast?
+ ;
+
+numberList
+ : L_BRACKET NUMBER (COMMA NUMBER)* R_BRACKET
+ ;
+
+// ==================== Sink block ====================
+
+sinkBlock
+ : SINK L_BRACE sinkContent R_BRACE
+ ;
+
+sinkContent
+ : (sinkStatement | SEMI)*
+ ;
+
+sinkStatement
+ : samplerBlock
+ | enforcerStatement
+ | dropperStatement
+ | ifStatement
+ | abortBlock
+ ;
+
+// ==================== Persist block ====================
+
+// The span's own fate, voted on with the same statements a sink uses.
+persistBlock
+ : PERSIST L_BRACE persistContent R_BRACE
+ ;
+
+persistContent
+ : (persistStatement | SEMI)*
+ ;
+
+persistStatement
+ : samplerBlock
+ | enforcerStatement
+ | dropperStatement
+ | ifStatement
+ | abortBlock
+ ;
+
+samplerBlock
+ : SAMPLER L_BRACE samplerContent R_BRACE
+ ;
+
+samplerContent
+ : (rateLimitBlock | ifStatement | SEMI)*
+ ;
+
+rateLimitBlock
+ : RATE_LIMIT L_PAREN rateLimitId R_PAREN L_BRACE rateLimitContent R_BRACE
+ ;
+
+rateLimitId
+ : STRING
+ ;
+
+rateLimitContent
+ : RPM NUMBER
+ ;
+
+enforcerStatement
+ : ENFORCER L_BRACE R_BRACE
+ ;
+
+dropperStatement
+ : DROPPER L_BRACE R_BRACE
+ ;
+
+// ==================== Control flow ====================
+
+ifStatement
+ : IF L_PAREN condition R_PAREN L_BRACE
+ ifBody
+ R_BRACE
+ (ELSE IF L_PAREN condition R_PAREN L_BRACE
+ ifBody
+ R_BRACE)*
+ (ELSE L_BRACE
+ ifBody
+ R_BRACE)?
+ ;
+
+ifBody
+ : (filterStatement | SEMI)*
+ | (extractorStatement | SEMI)*
+ | (sinkStatement | SEMI)*
+ | (persistStatement | SEMI)*
+ | samplerContent
+ ;
+
+// ==================== Conditions ====================
+
+// Alternative order is precedence in an ANTLR left-recursive rule: NOT binds tightest, then AND, then OR, so
+// `!peer && hasAttr("x")` is `(!peer) && hasAttr("x")`, as in Java.
+condition
+ : NOT condition # condNot
+ | condition AND condition # condAnd
+ | condition OR condition # condOr
+ | conditionExpr DEQ conditionExpr # condEq
+ | conditionExpr NEQ conditionExpr # condNeq
+ | conditionExpr GT conditionExpr # condGt
+ | conditionExpr LT conditionExpr # condLt
+ | conditionExpr GTE conditionExpr # condGte
+ | conditionExpr LTE conditionExpr # condLte
+ | conditionExpr # condSingle
+ ;
+
+conditionExpr
+ : valueAccess typeCast? # condValueAccess
+ | L_PAREN condition R_PAREN # condParenGroup
+ | STRING # condString
+ | NUMBER # condNumber
+ | boolValue # condBool
+ | NULL # condNull
+ | functionInvocation # condFunctionCall
+ ;
+
+// ==================== Value access ====================
+
+// Accessing the span, the metadata and the span's attributes:
+// span.name, span?.status?.message, span.eventsCount
+// meta.service, meta.latency, meta.kind, meta.root
+// attr("db.system.name", "db.system"), hasAttr("http.route"), resource("telemetry.sdk.language")
+// service(meta.service, meta.layer), serviceRelation(CLIENT, src, srcLayer, dst, dstLayer, comp)
+
+// Arithmetic / string-concat expressions. Operator precedence: * / bind tighter than + -.
+// All four operators share the same flattened model in the AST: each level produces a list of
+// operands plus a list of operators (size N-1).
+valueAccess
+ : valueAccessAdd
+ ;
+
+valueAccessAdd
+ : valueAccessMul ((PLUS | MINUS) valueAccessMul)*
+ ;
+
+valueAccessMul
+ : valueAccessTerm ((STAR | SLASH) valueAccessTerm)*
+ ;
+
+valueAccessTerm
+ : valueAccessPrimary (valueAccessSegment)*
+ ;
+
+valueAccessPrimary
+ : SPAN # valueSpan
+ | META # valueMeta
+ | IDENTIFIER # valueIdentifier
+ | STRING # valueString
+ | NUMBER # valueNumber
+ | boolValue # valueBool
+ | NULL # valueNull
+ | functionInvocation # valueFunctionCall
+ | L_PAREN valueAccess typeCast? R_PAREN # valueParen
+ ;
+
+valueAccessSegment
+ : DOT anyIdentifier # segmentField
+ | QUESTION DOT anyIdentifier # segmentSafeField
+ | DOT functionInvocation # segmentMethod
+ | QUESTION DOT functionInvocation # segmentSafeMethod
+ | L_BRACKET NUMBER R_BRACKET # segmentIndex
+ ;
+
+// The entity constructors are ordinary invocations the compiler recognizes by name, so
+// `service`, `instance` and `endpoint` have to be usable here as well as as statements.
+functionInvocation
+ : functionName L_PAREN functionArgList? R_PAREN
+ ;
+
+functionName
+ : anyIdentifier
+ ;
+
+functionArgList
+ : functionArg (COMMA functionArg)*
+ ;
+
+functionArg
+ : detectPoint
+ | valueAccess typeCast?
+ | STRING
+ | NUMBER
+ | boolValue
+ | NULL
+ ;
+
+detectPoint
+ : CLIENT
+ | SERVER
+ ;
+
+// ==================== Type cast ====================
+
+typeCast
+ : AS (STRING_TYPE | LONG_TYPE | INTEGER_TYPE | DOUBLE_TYPE | FLOAT_TYPE | BOOLEAN_TYPE | qualifiedName)
+ ;
+
+qualifiedName
+ : IDENTIFIER (DOT IDENTIFIER)*
+ ;
+
+// ==================== Common ====================
+
+// Allows keywords to be used as identifiers in contexts like output field names, label keys
+// and chain segments, so `labels service: meta.service` and `meta.status` parse.
+anyIdentifier
+ : IDENTIFIER
+ | SERVICE | INSTANCE | ENDPOINT | LAYER
+ | TAG | METRICS | ALIAS
+ | NAME | SCOPE | FUNCTION | VALUE | MATCH | STATUS
+ | LABELS | BUCKETS | RANKS | TIMESTAMP
+ | SAMPLER | RATE_LIMIT | RPM | ENFORCER | DROPPER
+ | FILTER | EXTRACTOR | SINK | PERSIST | ABORT
+ | DEF
+ ;
+
+boolValue
+ : TRUE | FALSE
+ ;
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/ExprType.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/ExprType.java
new file mode 100644
index 0000000000..ae0dcb1f94
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/ExprType.java
@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+/**
+ * The static type the compiler infers for an expression, driving arithmetic promotion, comparison widening and
+ * cast emission. Each numeric variant carries its Java keyword, its wrapper class name, its primitive
+ * {@link Class} and the runtime-helper method that converts an arbitrary object to that primitive.
+ */
+public enum ExprType {
+ INT("int", "Integer", int.class, "h.toInt"),
+ LONG("long", "Long", long.class, "h.toLong"),
+ FLOAT("float", "Float", float.class, "h.toFloat"),
+ DOUBLE("double", "Double", double.class, "h.toDouble"),
+ STRING(null, null, null, "h.toStr"),
+ BOOLEAN(null, null, null, "h.toBool"),
+ OBJECT(null, null, null, null),
+ UNKNOWN(null, null, null, null);
+
+ public final String primitiveKeyword;
+ public final String wrapperName;
+ public final Class<?> primitiveClass;
+ public final String runtimeHelper;
+
+ ExprType(final String primitiveKeyword, final String wrapperName,
+ final Class<?> primitiveClass, final String runtimeHelper) {
+ this.primitiveKeyword = primitiveKeyword;
+ this.wrapperName = wrapperName;
+ this.primitiveClass = primitiveClass;
+ this.runtimeHelper = runtimeHelper;
+ }
+
+ public boolean isNumeric() {
+ return this == INT || this == LONG || this == FLOAT || this == DOUBLE;
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALBlockCodegen.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALBlockCodegen.java
new file mode 100644
index 0000000000..5b00b59aa8
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALBlockCodegen.java
@@ -0,0 +1,717 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.apache.skywalking.oap.server.core.dsl.DslJavaSourceText;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionArg;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+
+/**
+ * Turns a rule's blocks into generated Java: the extractor and its {@code metrics} blocks, the sink and the
+ * persist vote. Expressions inside them are generated by {@link TALValueCodegen}.
+ */
+final class TALBlockCodegen {
+ private static final String HELPER = "org.apache.skywalking.oap.trace.analyzer.v2.compiler.rt.TalRuntimeHelper";
+ private static final String METER_ENTITY = "org.apache.skywalking.oap.server.core.analysis.meter.MeterEntity";
+ private static final String ACCEPTABLE_VALUE =
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.AcceptableValue";
+ private static final String BUCKETED_VALUES =
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.BucketedValues";
+ private static final String PERCENTILE_ARGUMENT =
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.PercentileArgument";
+ private static final String APDEX_ARGUMENT =
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.ApdexArgument";
+ private static final String DATA_TABLE = "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable";
+ private static final String DETECT_POINT = "org.apache.skywalking.oap.server.core.source.DetectPoint";
+
+ private TALBlockCodegen() {
+ }
+
+ /**
+ * The rule's own statements, in the order the DSL wrote them: extractor first, then the record's fate, then
+ * the span's. A block is skipped once the rule has aborted.
+ */
+ static void generateTopLevel(final StringBuilder sb,
+ final List<TALScriptModel.FilterStatement> stmts,
+ final TALGenCtx genCtx) {
+ for (final TALScriptModel.FilterStatement stmt : stmts) {
+ if (stmt instanceof TALScriptModel.ExtractorBlock) {
+ generateExtractorMethod(sb, (TALScriptModel.ExtractorBlock) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.SinkBlock) {
+ generateVoteBlock(sb, ((TALScriptModel.SinkBlock) stmt).getStatements(), genCtx, false);
+ } else if (stmt instanceof TALScriptModel.PersistBlock) {
+ generateVoteBlock(sb, ((TALScriptModel.PersistBlock) stmt).getStatements(), genCtx, true);
+ } else if (stmt instanceof TALScriptModel.AbortStatement) {
+ sb.append(" ctx.abort();\n");
+ sb.append(" return;\n");
+ } else if (stmt instanceof TALScriptModel.IfBlock) {
+ generateIfBlock(sb, (TALScriptModel.IfBlock) stmt, genCtx, false);
+ } else if (stmt instanceof TALScriptModel.DefStatement) {
+ TALDefCodegen.generateDefStatement(sb, (TALScriptModel.DefStatement) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.AliasStatement) {
+ generateAliasStatement(sb, (TALScriptModel.AliasStatement) stmt, genCtx);
+ } else {
+ throw new IllegalArgumentException(
+ "Unsupported top-level TAL statement: " + stmt.getClass().getSimpleName());
+ }
+ }
+ }
+
+ /**
+ * A {@code sink} or {@code persist} block. An empty one is still a vote: it says keep.
+ */
+ private static void generateVoteBlock(final StringBuilder sb,
+ final List<TALScriptModel.VoteStatement> stmts,
+ final TALGenCtx genCtx,
+ final boolean inPersist) {
+ sb.append(" if (!ctx.isAborted()) {\n");
+ if (stmts.isEmpty()) {
+ sb.append(" filterSpec.").append(inPersist ? "persist" : "sink").append("(ctx);\n");
+ } else {
+ final List<TALScriptModel.FilterStatement> asFilter = new ArrayList<>(stmts.size());
+ for (final TALScriptModel.VoteStatement vs : stmts) {
+ asFilter.add((TALScriptModel.FilterStatement) vs);
+ }
+ if (inPersist) {
+ // A persist block that votes at all has voted keep unless a statement says otherwise, so the
+ // default is recorded before the statements run.
+ sb.append(" filterSpec.persist(ctx);\n");
+ }
+ generateStatements(sb, asFilter, genCtx, inPersist);
+ }
+ sb.append(" }\n");
+ }
+
+ // ==================== Extractor ====================
+
+ /**
+ * Emit the extractor as a private method and the guarded call to it, so the abort flag is checked once at
+ * the block boundary rather than before every statement.
+ */
+ static void generateExtractorMethod(final StringBuilder sb,
+ final TALScriptModel.ExtractorBlock block,
+ final TALGenCtx genCtx) {
+ final String methodName = genCtx.nextMethodName("extractor");
+ final Object[] savedState = genCtx.saveProtoVarState();
+ genCtx.resetProtoVars();
+
+ final List<TALScriptModel.FilterStatement> stmts = new ArrayList<>();
+ for (final TALScriptModel.ExtractorStatement es : block.getStatements()) {
+ stmts.add((TALScriptModel.FilterStatement) es);
+ }
+ final StringBuilder bodyContent = new StringBuilder();
+ generateStatements(bodyContent, stmts, genCtx, false);
+
+ final StringBuilder body = new StringBuilder();
+ body.append("private void ").append(methodName).append("(").append(HELPER).append(" h) {\n");
+
+ final List<String[]> lvtVars = new ArrayList<>();
+ lvtVars.add(new String[] {"h", "L" + HELPER.replace('.', '/') + ";"});
+ appendRootDeclarations(body, lvtVars, genCtx);
+
+ body.append(bodyContent);
+ body.append("}\n");
+ genCtx.privateMethods.add(new TALPrivateMethod(body.toString(), lvtVars.toArray(new String[0][])));
+ genCtx.restoreProtoVarState(savedState);
+
+ sb.append(" if (!ctx.isAborted()) {\n");
+ sb.append(" ").append(methodName).append("(h);\n");
+ sb.append(" }\n");
+ }
+
+ /**
+ * Declare the cast input and any cached chain or local variables the block's expressions used. Collected
+ * while generating the body, so this runs after it and prepends.
+ */
+ private static void appendRootDeclarations(final StringBuilder body,
+ final List<String[]> lvtVars,
+ final TALGenCtx genCtx) {
+ if (genCtx.usedProtoAccess) {
+ // The cast is only needed when a chain was rooted at `span`; the cached chain variables are needed
+ // whenever any typed chain ran, `meta.*` included.
+ if (genCtx.inputType != null) {
+ final String typeName = genCtx.inputType.getName();
+ body.append(" ").append(typeName).append(" _p = (")
+ .append(typeName).append(") h.ctx().getInput();\n");
+ lvtVars.add(new String[] {"_p", "L" + typeName.replace('.', '/') + ";"});
+ }
+ body.append(genCtx.protoVarDecls);
+ lvtVars.addAll(genCtx.protoLvtVars);
+ }
+ if (genCtx.outputType != null) {
+ final String outName = genCtx.outputType.getName();
+ body.append(" ").append(outName).append(" _o = (")
+ .append(outName).append(") h.ctx().getOutput();\n");
+ lvtVars.add(new String[] {"_o", "L" + outName.replace('.', '/') + ";"});
+ }
+ if (genCtx.localVarDecls.length() > 0) {
+ body.append(genCtx.localVarDecls);
+ lvtVars.addAll(genCtx.localVarLvtVars);
+ }
+ }
+
+ /**
+ * Dispatch a list of statements. {@code inPersist} tells the vote statements which thing they decide, the
+ * record or the span, since {@code sink} and {@code persist} share their statement set.
+ */
+ static void generateStatements(final StringBuilder sb,
+ final List<? extends TALScriptModel.FilterStatement> stmts,
+ final TALGenCtx genCtx,
+ final boolean inPersist) {
+ for (final TALScriptModel.FilterStatement stmt : stmts) {
+ generateStatement(sb, stmt, genCtx, inPersist);
+ }
+ }
+
+ private static void generateStatement(final StringBuilder sb,
+ final TALScriptModel.FilterStatement stmt,
+ final TALGenCtx genCtx,
+ final boolean inPersist) {
+ if (stmt instanceof TALScriptModel.AbortStatement) {
+ sb.append(" h.ctx().abort();\n");
+ sb.append(" return;\n");
+ } else if (stmt instanceof TALScriptModel.DefStatement) {
+ TALDefCodegen.generateDefStatement(sb, (TALScriptModel.DefStatement) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.FieldAssignment) {
+ generateFieldAssignment(sb, (TALScriptModel.FieldAssignment) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.OutputFieldAssignment) {
+ generateOutputFieldAssignment(sb, (TALScriptModel.OutputFieldAssignment) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.TagAssignment) {
+ generateTagAssignment(sb, (TALScriptModel.TagAssignment) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.AliasStatement) {
+ generateAliasStatement(sb, (TALScriptModel.AliasStatement) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.MetricsBlock) {
+ generateMetricsBlock(sb, (TALScriptModel.MetricsBlock) stmt, genCtx);
+ } else if (stmt instanceof TALScriptModel.EnforcerStatement) {
+ sb.append(" filterSpec.enforcer(h.ctx(), ").append(inPersist).append(");\n");
+ } else if (stmt instanceof TALScriptModel.DropperStatement) {
+ sb.append(" filterSpec.dropper(h.ctx(), ").append(inPersist).append(");\n");
+ } else if (stmt instanceof TALScriptModel.SamplerBlock) {
+ generateSamplerBlock(sb, (TALScriptModel.SamplerBlock) stmt, genCtx, inPersist);
+ } else if (stmt instanceof TALScriptModel.IfBlock) {
+ generateIfBlock(sb, (TALScriptModel.IfBlock) stmt, genCtx, inPersist);
+ } else {
+ throw new IllegalArgumentException(
+ "Unsupported TAL statement in codegen: " + stmt.getClass().getSimpleName());
+ }
+ }
+
+ private static void generateIfBlock(final StringBuilder sb,
+ final TALScriptModel.IfBlock block,
+ final TALGenCtx genCtx,
+ final boolean inPersist) {
+ sb.append(" if (");
+ TALValueCodegen.generateCondition(sb, block.getCondition(), genCtx);
+ sb.append(") {\n");
+ generateStatements(sb, block.getThenStatements(), genCtx, inPersist);
+ sb.append(" }\n");
+ if (!block.getElseStatements().isEmpty()) {
+ sb.append(" else {\n");
+ generateStatements(sb, block.getElseStatements(), genCtx, inPersist);
+ sb.append(" }\n");
+ }
+ }
+
+ /**
+ * {@code service}, {@code instance}, {@code endpoint} and {@code layer} overwrite the metadata view, which is
+ * also what names the record's standard fields.
+ */
+ private static void generateFieldAssignment(final StringBuilder sb,
+ final TALScriptModel.FieldAssignment stmt,
+ final TALGenCtx genCtx) {
+ final String setter;
+ switch (stmt.getFieldType()) {
+ case SERVICE:
+ setter = "setService";
+ break;
+ case INSTANCE:
+ setter = "setServiceInstance";
+ break;
+ case ENDPOINT:
+ setter = "setEndpoint";
+ break;
+ case LAYER:
+ default:
+ setter = "setLayer";
+ break;
+ }
+ sb.append(" h.ctx().getMeta().").append(setter).append("(");
+ TALValueCodegen.generateStringValueAccess(sb, stmt.getValue(), stmt.getCastType(), genCtx);
+ sb.append(");\n");
+ }
+
+ private static void generateOutputFieldAssignment(final StringBuilder sb,
+ final TALScriptModel.OutputFieldAssignment stmt,
+ final TALGenCtx genCtx) {
+ if (genCtx.outputType == null) {
+ throw new IllegalArgumentException(
+ "Output field '" + stmt.getFieldName() + "' needs the rule to declare an outputType");
+ }
+ final java.lang.reflect.Method setter = findSetter(genCtx.outputType, stmt.getFieldName());
+ sb.append(" _o.").append(setter.getName()).append("(");
+ TALValueCodegen.generateCastedValueAccess(sb, stmt.getValue(),
+ castFor(setter.getParameterTypes()[0], stmt.getCastType()), genCtx);
+ sb.append(");\n");
+ }
+
+ /**
+ * @return the setter for an output field, or a compile error naming what the builder does offer
+ */
+ private static java.lang.reflect.Method findSetter(final Class<?> outputType, final String field) {
+ final String wanted = "set" + Character.toUpperCase(field.charAt(0)) + field.substring(1);
+ for (final java.lang.reflect.Method m : outputType.getMethods()) {
+ if (m.getName().equals(wanted) && m.getParameterCount() == 1) {
+ return m;
+ }
+ }
+ final List<String> available = new ArrayList<>();
+ for (final java.lang.reflect.Method m : outputType.getMethods()) {
+ if (m.getName().startsWith("set") && m.getParameterCount() == 1) {
+ available.add(Character.toLowerCase(m.getName().charAt(3)) + m.getName().substring(4));
+ }
+ }
+ throw new IllegalArgumentException(
+ "outputType " + outputType.getName() + " has no field '" + field + "'; it offers " + available);
+ }
+
+ /**
+ * A field statement with no explicit cast takes the setter's own parameter type, so
+ * {@code latency meta.latency} lands as an int without the rule saying so.
+ */
+ private static String castFor(final Class<?> parameterType, final String declaredCast) {
+ if (declaredCast != null) {
+ return declaredCast;
+ }
+ if (parameterType == int.class || parameterType == Integer.class) {
+ return "Integer";
+ }
+ if (parameterType == long.class || parameterType == Long.class) {
+ return "Long";
+ }
+ if (parameterType == double.class || parameterType == Double.class) {
+ return "Double";
+ }
+ if (parameterType == float.class || parameterType == Float.class) {
+ return "Float";
+ }
+ if (parameterType == boolean.class || parameterType == Boolean.class) {
+ return "Boolean";
+ }
+ return "String";
+ }
+
+ private static void generateTagAssignment(final StringBuilder sb,
+ final TALScriptModel.TagAssignment stmt,
+ final TALGenCtx genCtx) {
+ for (final Map.Entry<String, TALScriptModel.TagValue> e : stmt.getTags().entrySet()) {
+ sb.append(" h.ctx().addTag(\"").append(DslJavaSourceText.toLiteral(e.getKey())).append("\", ");
+ TALValueCodegen.generateStringValueAccess(
+ sb, e.getValue().getValue(), e.getValue().getCastType(), genCtx);
+ sb.append(");\n");
+ }
+ }
+
+ private static void generateAliasStatement(final StringBuilder sb,
+ final TALScriptModel.AliasStatement stmt,
+ final TALGenCtx genCtx) {
+ sb.append(" h.alias(");
+ TALValueCodegen.generateStringValueAccess(sb, stmt.getAddress(), stmt.getCastType(), genCtx);
+ sb.append(");\n");
+ }
+
+ private static void generateSamplerBlock(final StringBuilder sb,
+ final TALScriptModel.SamplerBlock block,
+ final TALGenCtx genCtx,
+ final boolean inPersist) {
+ for (final TALScriptModel.SamplerContent content : block.getContents()) {
+ if (content instanceof TALScriptModel.RateLimitBlock) {
+ final TALScriptModel.RateLimitBlock rl = (TALScriptModel.RateLimitBlock) content;
+ sb.append(" filterSpec.rateLimit(h.ctx(), ");
+ appendRateLimitId(sb, rl, genCtx);
+ sb.append(", ").append(rl.getRpm()).append(", ").append(inPersist).append(");\n");
+ } else if (content instanceof TALScriptModel.IfBlock) {
+ generateIfBlock(sb, (TALScriptModel.IfBlock) content, genCtx, inPersist);
+ }
+ }
+ }
+
+ /**
+ * A {@code ${...}} placeholder makes the id per-span, so the counter is built at runtime; a plain id is a
+ * constant.
+ */
+ private static void appendRateLimitId(final StringBuilder sb,
+ final TALScriptModel.RateLimitBlock rl,
+ final TALGenCtx genCtx) {
+ if (!rl.isIdInterpolated()) {
+ sb.append("\"").append(DslJavaSourceText.toLiteral(rl.getId())).append("\"");
+ return;
+ }
+ sb.append("(\"\"");
+ for (final TALScriptModel.InterpolationPart part : rl.getIdParts()) {
+ sb.append(" + ");
+ if (part.isLiteral()) {
+ sb.append("\"").append(DslJavaSourceText.toLiteral(part.getText())).append("\"");
+ } else {
+ TALValueCodegen.generateStringValueAccess(sb, part.getExpression(), null, genCtx);
+ }
+ }
+ sb.append(")");
+ }
+
+ // ==================== Metrics ====================
+
+ /**
+ * One {@code metrics {}} block becomes the sequence the SWIP specifies: build the entity, register its
+ * traffic once, build the metric, accept the observation and send it in the span's minute bucket.
+ */
+ private static void generateMetricsBlock(final StringBuilder sb,
+ final TALScriptModel.MetricsBlock block,
+ final TALGenCtx genCtx) {
+ final TALMetricFunction function = TALMetricFunction.of(block.getFunction());
+ final String fullName = genCtx.metricPrefix == null || genCtx.metricPrefix.isEmpty()
+ ? block.getName() : genCtx.metricPrefix + "_" + block.getName();
+ validate(block, function, fullName);
+
+ final String entityVar = genCtx.nextLocalName("_e");
+ final String valueVar = genCtx.nextLocalName("_v");
+
+ sb.append(" {\n");
+ sb.append(" ").append(METER_ENTITY).append(" ").append(entityVar).append(" = ");
+ final String scopeType = appendEntity(sb, block.getScope(), genCtx);
+ sb.append(";\n");
+ // A layer name that is not registered resolves to null, see TalRuntimeHelper.layer, and the block is skipped
+ // rather than filed under a layer the rule did not name.
+ sb.append(" if (h.layerResolved(").append(entityVar).append(")) {\n");
+ sb.append(" h.traffic(").append(entityVar).append(");\n");
+ sb.append(" ").append(ACCEPTABLE_VALUE).append(" ").append(valueVar)
+ .append(" = h.meterSystem().buildMetrics(\"")
+ .append(DslJavaSourceText.toLiteral(fullName)).append("\", ")
+ .append(function.valueClass).append(".class);\n");
+ sb.append(" ").append(valueVar).append(".accept(").append(entityVar).append(", ");
+ appendObservation(sb, block, function, genCtx);
+ sb.append(");\n");
+ sb.append(" h.send(").append(valueVar).append(", ");
+ if (block.getTimestamp() != null) {
+ sb.append("h.toLong(");
+ TALValueCodegen.generateValueAccessObj(sb, block.getTimestamp(), null, genCtx);
+ sb.append(")");
+ } else {
+ sb.append("h.ctx().getMeta().getTimestamp()");
+ }
+ sb.append(");\n");
+ sb.append(" }\n");
+ sb.append(" }\n");
+
+ genCtx.metricDeclarations.add(
+ new TALMetricDeclaration(fullName, function.meterFunction, scopeType, block.getName()));
+ }
+
+ /**
+ * The observation the function accepts: a number for most, the {@code match} condition for {@code percent},
+ * an argument object for {@code apdex}, and a bucketed or labeled value for the rest.
+ */
+ private static void appendObservation(final StringBuilder sb,
+ final TALScriptModel.MetricsBlock block,
+ final TALMetricFunction function,
+ final TALGenCtx genCtx) {
+ switch (function.kind) {
+ case BOOLEAN:
+ sb.append("Boolean.valueOf(");
+ TALValueCodegen.generateCondition(sb, block.getMatch(), genCtx);
+ sb.append(")");
+ break;
+ case APDEX:
+ sb.append("new ").append(APDEX_ARGUMENT).append("(h.toInt(");
+ TALValueCodegen.generateValueAccessObj(sb, block.getValue(), null, genCtx);
+ sb.append("), h.ctx().getMeta().getService(), ");
+ sb.append("Boolean.valueOf(");
+ TALValueCodegen.generateCondition(sb, block.getStatus(), genCtx);
+ sb.append(").booleanValue())");
+ break;
+ case HISTOGRAM:
+ appendBucketedValues(sb, block, genCtx);
+ break;
+ case PERCENTILE:
+ sb.append("new ").append(PERCENTILE_ARGUMENT).append("(");
+ appendBucketedValues(sb, block, genCtx);
+ sb.append(", ").append(ranksArray(block)).append(")");
+ break;
+ case LABELED:
+ appendLabeledValue(sb, block, genCtx);
+ break;
+ case LONG:
+ default:
+ sb.append("Long.valueOf(h.toLong(");
+ TALValueCodegen.generateValueAccessObj(sb, block.getValue(), null, genCtx);
+ sb.append("))");
+ break;
+ }
+ }
+
+ /**
+ * Place the observation in the first bucket whose bound is not below it; a value above the last bound lands
+ * in the last bucket, so that bound is a finite overflow sentinel.
+ */
+ private static void appendBucketedValues(final StringBuilder sb,
+ final TALScriptModel.MetricsBlock block,
+ final TALGenCtx genCtx) {
+ final List<String> buckets = block.getBuckets();
+ sb.append("h.bucketed(new long[] {");
+ for (int i = 0; i < buckets.size(); i++) {
+ if (i > 0) {
+ sb.append(", ");
+ }
+ sb.append(buckets.get(i)).append("L");
+ }
+ sb.append("}, h.toLong(");
+ TALValueCodegen.generateValueAccessObj(sb, block.getValue(), null, genCtx);
+ sb.append("))");
+ }
+
+ private static String ranksArray(final TALScriptModel.MetricsBlock block) {
+ final List<String> ranks = block.getRanks().isEmpty()
+ ? List.of("50", "75", "90", "95", "99") : block.getRanks();
+ final StringBuilder out = new StringBuilder("new int[] {");
+ for (int i = 0; i < ranks.size(); i++) {
+ if (i > 0) {
+ out.append(", ");
+ }
+ out.append(ranks.get(i));
+ }
+ return out.append("}").toString();
+ }
+
+ private static void appendLabeledValue(final StringBuilder sb,
+ final TALScriptModel.MetricsBlock block,
+ final TALGenCtx genCtx) {
+ sb.append("h.labeled(new String[] {");
+ int i = 0;
+ for (final Map.Entry<String, TALScriptModel.TagValue> e : block.getLabels().entrySet()) {
+ if (i++ > 0) {
+ sb.append(", ");
+ }
+ sb.append("\"").append(DslJavaSourceText.toLiteral(e.getKey())).append("\", ");
+ TALValueCodegen.generateStringValueAccess(
+ sb, e.getValue().getValue(), e.getValue().getCastType(), genCtx);
+ }
+ sb.append("}, h.toLong(");
+ TALValueCodegen.generateValueAccessObj(sb, block.getValue(), null, genCtx);
+ sb.append("))");
+ }
+
+ /**
+ * Emit the entity a {@code scope} names: an inline constructor, or a {@code def} variable already holding
+ * one.
+ *
+ * @return the {@code ScopeType} name the metric is registered under
+ */
+ private static String appendEntity(final StringBuilder sb,
+ final TALValueAccess scope,
+ final TALGenCtx genCtx) {
+ if (scope == null) {
+ throw new IllegalArgumentException("a metrics block needs a scope");
+ }
+ final String constructor = scope.getFunctionCallName();
+ if (constructor == null) {
+ final String varName = scope.getSegments().get(0);
+ final String scopeType = genCtx.entityScopeTypes.get(varName);
+ if (scopeType == null) {
+ throw new IllegalArgumentException(
+ "scope '" + varName + "' is not an entity; assign one with an entity constructor first");
+ }
+ sb.append("_def_").append(varName);
+ return scopeType;
+ }
+ return appendEntityConstructor(sb, scope, genCtx);
+ }
+
+ /**
+ * The entity constructors, recognized by name. Each maps onto a {@code MeterEntity} factory; the relation
+ * ones take a layer per side, because a span's peer is conjectured while its own service is not.
+ */
+ static String appendEntityConstructor(final StringBuilder sb,
+ final TALValueAccess scope,
+ final TALGenCtx genCtx) {
+ final String name = scope.getFunctionCallName();
+ final List<? extends TALFunctionArg> args = scope.getFunctionCallArgs();
+ switch (name) {
+ case "service":
+ requireArgs(name, args, 2);
+ sb.append(METER_ENTITY).append(".newService(");
+ str(sb, args, 0, genCtx);
+ sb.append(", ");
+ layer(sb, args, 1, genCtx);
+ sb.append(")");
+ return "SERVICE";
+ case "instance":
+ requireArgs(name, args, 3);
+ sb.append(METER_ENTITY).append(".newServiceInstance(");
+ str(sb, args, 0, genCtx);
+ sb.append(", ");
+ str(sb, args, 1, genCtx);
+ sb.append(", ");
+ layer(sb, args, 2, genCtx);
+ sb.append(", null)");
+ return "SERVICE_INSTANCE";
+ case "endpoint":
+ requireArgs(name, args, 3);
+ sb.append(METER_ENTITY).append(".newEndpoint(");
+ str(sb, args, 0, genCtx);
+ sb.append(", ");
+ str(sb, args, 1, genCtx);
+ sb.append(", ");
+ layer(sb, args, 2, genCtx);
+ sb.append(")");
+ return "ENDPOINT";
+ case "serviceRelation":
+ requireArgs(name, args, 6);
+ sb.append(METER_ENTITY).append(".newServiceRelation(");
+ str(sb, args, 1, genCtx);
+ sb.append(", ");
+ layer(sb, args, 2, genCtx);
+ sb.append(", ");
+ str(sb, args, 3, genCtx);
+ sb.append(", ");
+ layer(sb, args, 4, genCtx);
+ sb.append(", ").append(detectPoint(args.get(0))).append(", ");
+ intArg(sb, args, 5, genCtx);
+ sb.append(")");
+ return "SERVICE_RELATION";
+ case "serviceInstanceRelation":
+ requireArgs(name, args, 8);
+ sb.append(METER_ENTITY).append(".newServiceInstanceRelation(");
+ str(sb, args, 1, genCtx);
+ sb.append(", ");
+ str(sb, args, 2, genCtx);
+ sb.append(", ");
+ layer(sb, args, 3, genCtx);
+ sb.append(", ");
+ str(sb, args, 4, genCtx);
+ sb.append(", ");
+ str(sb, args, 5, genCtx);
+ sb.append(", ");
+ layer(sb, args, 6, genCtx);
+ sb.append(", ").append(detectPoint(args.get(0))).append(", ");
+ intArg(sb, args, 7, genCtx);
+ sb.append(")");
+ return "SERVICE_INSTANCE_RELATION";
+ default:
+ throw new IllegalArgumentException(
+ "'" + name + "' is not an entity constructor; expected one of "
+ + TALSpanRootResolver.ENTITY_CONSTRUCTORS);
+ }
+ }
+
+ private static void str(final StringBuilder sb, final List<? extends TALFunctionArg> args,
+ final int index, final TALGenCtx genCtx) {
+ TALValueCodegen.generateStringValueAccess(
+ sb, args.get(index).getValue(), args.get(index).getCastType(), genCtx);
+ }
+
+ private static void layer(final StringBuilder sb, final List<? extends TALFunctionArg> args,
+ final int index, final TALGenCtx genCtx) {
+ sb.append("h.layer(");
+ str(sb, args, index, genCtx);
+ sb.append(")");
+ }
+
+ private static void intArg(final StringBuilder sb, final List<? extends TALFunctionArg> args,
+ final int index, final TALGenCtx genCtx) {
+ sb.append("h.toInt(");
+ TALValueCodegen.generateValueAccessObj(sb, args.get(index).getValue(), null, genCtx);
+ sb.append(")");
+ }
+
+ private static String detectPoint(final TALFunctionArg arg) {
+ final String text = arg.getValue().getSegments().get(0);
+ if (!"CLIENT".equals(text) && !"SERVER".equals(text)) {
+ throw new IllegalArgumentException(
+ "a relation constructor's first argument is CLIENT or SERVER, got '" + text + "'");
+ }
+ return DETECT_POINT + "." + text;
+ }
+
+ private static void requireArgs(final String name, final List<? extends TALFunctionArg> args,
+ final int expected) {
+ if (args.size() != expected) {
+ throw new IllegalArgumentException(
+ name + "() takes " + expected + " arguments, got " + args.size());
+ }
+ }
+
+ /**
+ * The shape checks the SWIP lists: every block names a metric, a scope and a function, and each function
+ * takes exactly the clauses it needs.
+ */
+ private static void validate(final TALScriptModel.MetricsBlock block,
+ final TALMetricFunction function,
+ final String fullName) {
+ if (block.getName() == null || block.getName().isEmpty()) {
+ throw new IllegalArgumentException("a metrics block needs a name");
+ }
+ if (block.getScope() == null) {
+ throw new IllegalArgumentException("metric " + fullName + " needs a scope");
+ }
+ final boolean wantsValue = function.kind != TALMetricFunction.Kind.BOOLEAN;
+ if (wantsValue && block.getValue() == null) {
+ throw new IllegalArgumentException("metric " + fullName + " needs a value");
+ }
+ if (!wantsValue && block.getValue() != null) {
+ throw new IllegalArgumentException("metric " + fullName + " takes match, not value");
+ }
+ if ((function.kind == TALMetricFunction.Kind.BOOLEAN) != (block.getMatch() != null)) {
+ throw new IllegalArgumentException(
+ "match belongs to percent only; metric " + fullName + " uses " + function.meterFunction);
+ }
+ if ((function.kind == TALMetricFunction.Kind.APDEX) != (block.getStatus() != null)) {
+ throw new IllegalArgumentException(
+ "status belongs to apdex only; metric " + fullName + " uses " + function.meterFunction);
+ }
+ if ((function.kind == TALMetricFunction.Kind.LABELED) != !block.getLabels().isEmpty()) {
+ throw new IllegalArgumentException(
+ "labels belong to the labeled functions only; metric " + fullName
+ + " uses " + function.meterFunction);
+ }
+ final boolean wantsBuckets = function.kind == TALMetricFunction.Kind.HISTOGRAM
+ || function.kind == TALMetricFunction.Kind.PERCENTILE;
+ if (wantsBuckets == block.getBuckets().isEmpty()) {
+ throw new IllegalArgumentException(
+ "buckets belong to histogram and percentile only; metric " + fullName
+ + " uses " + function.meterFunction);
+ }
+ if (!block.getRanks().isEmpty() && function.kind != TALMetricFunction.Kind.PERCENTILE) {
+ throw new IllegalArgumentException("ranks belong to percentile only; metric " + fullName);
+ }
+ requireAscending(block.getBuckets(), fullName);
+ }
+
+ private static void requireAscending(final List<String> buckets, final String fullName) {
+ long previous = Long.MIN_VALUE;
+ for (final String bucket : buckets) {
+ final long value = Long.parseLong(bucket);
+ if (value <= previous) {
+ throw new IllegalArgumentException(
+ "metric " + fullName + " has buckets that are not ascending: " + buckets);
+ }
+ previous = value;
+ }
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALClassGenerator.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALClassGenerator.java
new file mode 100644
index 0000000000..9b77712088
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALClassGenerator.java
@@ -0,0 +1,290 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.io.File;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import javassist.ClassPool;
+import javassist.CtClass;
+import javassist.CtMethod;
+import javassist.CtNewConstructor;
+import javassist.CtNewMethod;
+import lombok.Getter;
+import lombok.Setter;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.skywalking.oap.server.core.analysis.meter.MeterSystem;
+import org.apache.skywalking.oap.server.core.analysis.meter.ScopeType;
+import org.apache.skywalking.oap.server.core.dsl.DslClassNaming;
+import org.apache.skywalking.oap.server.core.dsl.DslGeneratedFileWriter;
+import org.apache.skywalking.oap.server.core.dsl.DslSourceRef;
+import org.apache.skywalking.oap.server.core.dsl.classloader.BytecodeClassDefiner;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.rt.TalExpressionPackageHolder;
+import org.apache.skywalking.oap.trace.analyzer.v2.dsl.TalExpression;
+import org.apache.skywalking.oap.trace.analyzer.v2.provider.TALConfigs;
+
+/**
+ * Compiles one TAL rule into a class implementing {@link TalExpression}.
+ *
+ * <p>The pipeline is the one every SkyWalking DSL uses: the parsed model becomes Java source, Javassist compiles
+ * it, and the class is loaded with a local-variable table and a source reference so a stack trace names the rule
+ * file. Blocks become private methods guarded by the abort flag; every method takes the context explicitly, so
+ * nothing rides on a {@code ThreadLocal}.
+ */
+@Slf4j
+public final class TALClassGenerator {
+ private static final String PACKAGE = "org.apache.skywalking.oap.trace.analyzer.v2.compiler.rt.";
+ private static final String FILTER_SPEC = "org.apache.skywalking.oap.trace.analyzer.v2.dsl.spec.FilterSpec";
+ private static final String EXEC_CTX = "org.apache.skywalking.oap.trace.analyzer.v2.dsl.ExecutionContext";
+ private static final String HELPER = "org.apache.skywalking.oap.trace.analyzer.v2.compiler.rt.TalRuntimeHelper";
+ private static final String EXPRESSION = "org.apache.skywalking.oap.trace.analyzer.v2.dsl.TalExpression";
+
+ private final ClassPool classPool;
+ private final ClassLoader targetClassLoader;
+ /**
+ * Where the generated {@code .class} and the Java source Javassist compiled are written. Null in normal
+ * operation: {@code resolveClassDumpDir} returns null unless {@code SW_DYNAMIC_CLASS_ENGINE_DEBUG} is set,
+ * and it builds its path from the OAP install directory, which a test JVM does not have. A test that wants
+ * the dump sets it explicitly through {@link #setClassOutputDir}.
+ */
+ private File classOutputDir;
+
+ /**
+ * The rule's declared input type, which the {@code span} root resolves against.
+ */
+ @Setter
+ private Class<?> inputType;
+
+ /**
+ * The record the rule builds, or null when it declares no {@code outputType}.
+ */
+ @Setter
+ private Class<?> outputType;
+
+ /**
+ * Write the generated class and the Java source Javassist compiled to this directory, whatever the
+ * environment says. Meant for tests: {@code SW_DYNAMIC_CLASS_ENGINE_DEBUG} resolves its path from the OAP
+ * install directory, which a test JVM does not have.
+ *
+ * @param dir the directory; the writer creates it on first write
+ */
+ public void setClassOutputDir(final File dir) {
+ this.classOutputDir = dir;
+ }
+
+ @Setter
+ private String classNameHint;
+
+ @Setter
+ private DslSourceRef sourceRef;
+
+ @Setter
+ private String metricPrefix;
+
+ /**
+ * The verbatim rule text, stamped on debug captures so the UI can render the source inline.
+ */
+ @Setter
+ private String content;
+
+ /**
+ * Every metric the compiled rule declares, available after {@link #compile}.
+ */
+ @Getter
+ private List<TALMetricDeclaration> metricDeclarations = List.of();
+
+ public TALClassGenerator() {
+ this(ClassPool.getDefault(), null);
+ }
+
+ /**
+ * Runtime-rule constructor: the caller supplies a per-file pool already scoped to a per-file loader, so the
+ * generated class is defined there rather than in the OAP app loader.
+ *
+ * @param classPool the pool to make the class in
+ * @param targetClassLoader the loader to define it in, or null for the app loader
+ */
+ public TALClassGenerator(final ClassPool classPool, final ClassLoader targetClassLoader) {
+ this.classPool = classPool;
+ this.targetClassLoader = targetClassLoader;
+ this.classOutputDir = DslGeneratedFileWriter.resolveClassDumpDir("tal");
+ }
+
+ /**
+ * Parse, generate and load one rule.
+ *
+ * @param dsl the rule's DSL text
+ * @return the compiled rule, ready to run against spans
+ * @throws Exception when the rule does not parse, does not validate, or does not compile
+ */
+ public TalExpression compile(final String dsl) throws Exception {
+ final TALScriptModel model = TALScriptParser.parse(dsl);
+ final TALGenCtx genCtx = new TALGenCtx(new TALSpanRootResolver(inputType), inputType, outputType);
+ genCtx.metricPrefix = metricPrefix;
+ genCtx.ruleName = classNameHint == null ? "tal" : classNameHint;
+
+ final String executeBody = generateExecuteMethod(model, genCtx);
+ this.metricDeclarations = List.copyOf(dedupeDeclarations(genCtx.metricDeclarations));
+
+ final String className = DslClassNaming.allocate(
+ PACKAGE + DslClassNaming.stem(sourceRef, genCtx.ruleName, TALConfigs.TAL_CATALOG),
+ targetClassLoader == null);
+
+ if (log.isDebugEnabled()) {
+ log.debug("TAL compile execute():\n{}", executeBody);
+ for (final TALPrivateMethod pm : genCtx.privateMethods) {
+ log.debug("TAL compile private method:\n{}", pm.source);
+ }
+ }
+
+ final CtClass ctClass = classPool.makeClass(className);
+ ctClass.addInterface(classPool.get(EXPRESSION));
+ ctClass.addConstructor(CtNewConstructor.defaultConstructor(ctClass));
+
+ final List<CtMethod> privateMethods = new ArrayList<>();
+ for (final TALPrivateMethod pm : genCtx.privateMethods) {
+ final CtMethod ctMethod = CtNewMethod.make(pm.source, ctClass);
+ ctClass.addMethod(ctMethod);
+ privateMethods.add(ctMethod);
+ DslGeneratedFileWriter.addLocalVariableTable(ctMethod, className, pm.lvtVars);
+ }
+
+ final CtMethod execMethod = CtNewMethod.make(executeBody, ctClass);
+ ctClass.addMethod(execMethod);
+
+ final List<String[]> execLvt = new ArrayList<>();
+ execLvt.add(new String[] {"filterSpec", "L" + FILTER_SPEC.replace('.', '/') + ";"});
+ execLvt.add(new String[] {"ctx", "L" + EXEC_CTX.replace('.', '/') + ";"});
+ execLvt.add(new String[] {"h", "L" + HELPER.replace('.', '/') + ";"});
+ if (genCtx.usedProtoAccess) {
+ if (inputType != null) {
+ execLvt.add(new String[] {"_p", "L" + inputType.getName().replace('.', '/') + ";"});
+ }
+ execLvt.addAll(genCtx.protoLvtVars);
+ }
+ execLvt.addAll(genCtx.localVarLvtVars);
+ DslGeneratedFileWriter.addLocalVariableTable(execMethod, className, execLvt.toArray(new String[0][]));
+
+ final String sourceText = buildSourceText(ctClass, genCtx, executeBody);
+ if (sourceRef != null) {
+ DslGeneratedFileWriter.setSourceFile(ctClass, sourceRef.sourceFileOf(ctClass.getSimpleName()));
+ }
+ DslGeneratedFileWriter.attachSignatureLine(
+ execMethod, DslGeneratedFileWriter.lineOfMethod(sourceText, "execute"));
+ for (final CtMethod pmMethod : privateMethods) {
+ DslGeneratedFileWriter.attachSignatureLine(
+ pmMethod, DslGeneratedFileWriter.lineOfMethod(sourceText, pmMethod.getName()));
+ }
+
+ DslGeneratedFileWriter.writeClassFile(classOutputDir, ctClass);
+ DslGeneratedFileWriter.writeSourceFile(classOutputDir, ctClass.getSimpleName(), sourceText);
+
+ final Class<?> clazz = BytecodeClassDefiner.define(
+ ctClass, targetClassLoader, TalExpressionPackageHolder.class);
+ ctClass.detach();
+ return (TalExpression) clazz.getDeclaredConstructor().newInstance();
+ }
+
+ /**
+ * Install the storage model for every metric the rule declared. Runs before the rule sees a span; on the
+ * boot path {@code create} is create-if-absent, as it is for MAL.
+ *
+ * @param meterSystem the meter system to register with
+ */
+ public void createMetrics(final MeterSystem meterSystem) {
+ for (final TALMetricDeclaration declaration : metricDeclarations) {
+ meterSystem.create(declaration.fullName, declaration.function,
+ ScopeType.valueOf(declaration.scopeType));
+ }
+ }
+
+ /**
+ * Two blocks declaring the same metric with the same shape share one metric, which is how {@code if}
+ * branches feed one series; the same name with a different function or scope is a compile error naming both.
+ */
+ private static List<TALMetricDeclaration> dedupeDeclarations(final List<TALMetricDeclaration> declarations) {
+ final Map<String, TALMetricDeclaration> byName = new LinkedHashMap<>();
+ final Set<TALMetricDeclaration> distinct = new LinkedHashSet<>(declarations);
+ for (final TALMetricDeclaration declaration : distinct) {
+ final TALMetricDeclaration previous = byName.put(declaration.fullName, declaration);
+ if (previous != null) {
+ throw new IllegalArgumentException(
+ "metric " + declaration.fullName + " is declared twice with different shapes: "
+ + previous + " and " + declaration);
+ }
+ }
+ return new ArrayList<>(byName.values());
+ }
+
+ private String generateExecuteMethod(final TALScriptModel model, final TALGenCtx genCtx) {
+ genCtx.resetProtoVars();
+
+ final StringBuilder bodyContent = new StringBuilder();
+ TALBlockCodegen.generateTopLevel(bodyContent, model.getStatements(), genCtx);
+
+ final StringBuilder sb = new StringBuilder();
+ sb.append("public void execute(").append(FILTER_SPEC)
+ .append(" filterSpec, ").append(EXEC_CTX).append(" ctx) {\n");
+ sb.append(" ").append(HELPER).append(" h = new ").append(HELPER)
+ .append("(ctx, filterSpec);\n");
+
+ if (outputType != null) {
+ sb.append(" ctx.setOutput(new ").append(outputType.getName()).append("());\n");
+ sb.append(" ctx.outputAsBuilder().bindInput(ctx.getMeta(), ctx.getInput());\n");
+ }
+
+ if (genCtx.usedProtoAccess) {
+ if (inputType != null) {
+ final String typeName = inputType.getName();
+ sb.append(" ").append(typeName).append(" _p = (")
+ .append(typeName).append(") ctx.getInput();\n");
+ }
+ sb.append(genCtx.protoVarDecls);
+ }
+ if (genCtx.localVarDecls.length() > 0) {
+ sb.append(genCtx.localVarDecls);
+ }
+
+ sb.append(bodyContent);
+ sb.append("}\n");
+ return sb.toString();
+ }
+
+ /**
+ * Assemble the exact Java source handed to Javassist, so the line numbers attached to the methods refer to
+ * text that exists rather than to an envelope reconstructed later.
+ */
+ private String buildSourceText(final CtClass ctClass, final TALGenCtx genCtx, final String executeBody) {
+ final StringBuilder out = new StringBuilder();
+ out.append("// generated from ")
+ .append(sourceRef == null ? "<unknown>" : sourceRef.toString()).append('\n');
+ out.append("public class ").append(ctClass.getSimpleName())
+ .append(" implements ").append(EXPRESSION).append(" {\n");
+ for (final TALPrivateMethod pm : genCtx.privateMethods) {
+ out.append(pm.source).append('\n');
+ }
+ out.append(executeBody);
+ out.append("}\n");
+ return out.toString();
+ }
+
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALCodegenHelper.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALCodegenHelper.java
new file mode 100644
index 0000000000..ecbb0b4f55
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALCodegenHelper.java
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Small helpers the generated Java source needs, shared by every DSL's codegen.
+ */
+public final class TALCodegenHelper {
+ /**
+ * The value-producing built-ins every DSL shares, mapping the name a rule writes to the runtime-helper method
+ * that implements it and the type it returns. A DSL's own vocabulary goes through
+ * {@link TALRootResolver#generateFunctionCall} instead.
+ */
+ public static final Map<String, Object[]> BUILTIN_FUNCTIONS = new HashMap<>();
+
+ static {
+ BUILTIN_FUNCTIONS.put("toJson", new Object[] {"h.toJsonObject", JsonObject.class});
+ BUILTIN_FUNCTIONS.put("toJsonArray", new Object[] {"h.toJsonArray", JsonArray.class});
+ }
+
+ private TALCodegenHelper() {
+ }
+
+ /**
+ * @param primitiveType a primitive class
+ * @return the wrapper type's simple name, or null when the argument is not one of the boxable primitives
+ */
+ public static String boxTypeName(final Class<?> primitiveType) {
+ if (primitiveType == int.class) {
+ return "Integer";
+ } else if (primitiveType == long.class) {
+ return "Long";
+ } else if (primitiveType == boolean.class) {
+ return "Boolean";
+ } else if (primitiveType == double.class) {
+ return "Double";
+ } else if (primitiveType == float.class) {
+ return "Float";
+ }
+ return null;
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALDefCodegen.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALDefCodegen.java
new file mode 100644
index 0000000000..625febc039
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALDefCodegen.java
@@ -0,0 +1,462 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALDefStatement;
+
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFieldSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionArg;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALIndexSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALMethodSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessSegment;
+
+import java.util.List;
+import java.lang.reflect.Method;
+
+/**
+ * Code generation for TAL {@code def} local variable declarations and
+ * typed method-chain resolution on def variables.
+ *
+ * <p>The {@code def} keyword declares a local variable in the extractor
+ * block. The type is inferred from the initializer expression, and
+ * subsequent method chains are resolved via compile-time reflection.
+ *
+ * <p>TAL example:
+ * <pre>{@code
+ * extractor {
+ * // def holding an entity, used as the scope of several metrics blocks
+ * def svc = service(meta.service, meta.layer)
+ *
+ * // def over attributes, reassigned in a branch: the declaration is hoisted, so this
+ * // assigns to the same variable rather than shadowing it
+ * def peer = attr("peer.service")
+ * if (!peer) {
+ * def peer = attr("server.address", "net.peer.name")
+ * }
+ *
+ * // def with an explicit type cast
+ * def status = attr("http.response.status_code") as Integer
+ * }
+ * }</pre>
+ *
+ * <p>Generated code declares Java locals with the {@code _def_} prefix
+ * (e.g. {@code _def_svc}, {@code _def_peer}) at the top of the method and emits
+ * assignments at the point where {@code def} appears in the DSL.
+ *
+ * <p>Sibling implementation: {@code LALDefCodegen} in {@code log-analyzer}. Separate copies
+ * by design; see {@link TALValueCodegen}.
+ */
+public final class TALDefCodegen {
+
+ private TALDefCodegen() {
+ // utility class
+ }
+
+ // ==================== Def statement codegen ====================
+
+ /**
+ * Generates a {@code def} variable declaration and assignment.
+ *
+ * <p>TAL: {@code def payload = toJson(attr("http.request.body"))}
+ *
+ * <p>Generated (declaration at method top):
+ * <pre>{@code
+ * com.google.gson.JsonObject _def_jwt;
+ * }</pre>
+ * <p>Generated (assignment at def site):
+ * <pre>{@code
+ * _def_jwt = h.toJsonObject(h.mapVal("metadata", "filterMetadataMap", "key"));
+ * }</pre>
+ *
+ * <p>Type inference: built-in functions ({@code toJson} →
+ * {@code JsonObject}, {@code toJsonArray} → {@code JsonArray}) have
+ * known return types. General expressions infer the type from
+ * {@code genCtx.lastResolvedType} after codegen. An explicit
+ * {@code as Type} cast overrides the inferred type.
+ */
+ public static void generateDefStatement(final StringBuilder sb,
+ final TALDefStatement def,
+ final TALGenCtx genCtx) {
+ final TALValueAccess init = def.getInitializer();
+ final String varName = def.getVarName();
+ final String javaVar = "_def_" + varName;
+ final boolean alreadyDeclared = genCtx.localVars.containsKey(varName);
+
+ // Determine type and generate initializer expression
+ Class<?> resolvedType;
+ final StringBuilder initExpr = new StringBuilder();
+
+ if (init.getFunctionCallName() != null
+ && TALSpanRootResolver.ENTITY_CONSTRUCTORS.contains(init.getFunctionCallName())) {
+ // An entity held in a def has a compile-time scope type, so `scope svc` always has one shape and
+ // reassigning the variable with a different constructor is caught here rather than at runtime.
+ final String scopeType = TALBlockCodegen.appendEntityConstructor(initExpr, init, genCtx);
+ final String previous = genCtx.entityScopeTypes.put(varName, scopeType);
+ if (previous != null && !previous.equals(scopeType)) {
+ throw new IllegalArgumentException(
+ "def " + varName + " was an entity of scope " + previous
+ + " and is reassigned as " + scopeType);
+ }
+ resolvedType = org.apache.skywalking.oap.server.core.analysis.meter.MeterEntity.class;
+ } else if (init.getFunctionCallName() != null
+ && TALCodegenHelper.BUILTIN_FUNCTIONS.containsKey(init.getFunctionCallName())) {
+ // Built-in function: toJson(...), toJsonArray(...)
+ final String funcName = init.getFunctionCallName();
+ final int argCount = init.getFunctionCallArgs().size();
+ if (argCount != 1) {
+ throw new IllegalArgumentException(
+ funcName + "() requires exactly 1 argument, got " + argCount);
+ }
+ final Object[] info = TALCodegenHelper.BUILTIN_FUNCTIONS.get(funcName);
+ final String helperMethod = (String) info[0];
+ resolvedType = (Class<?>) info[1];
+
+ initExpr.append(helperMethod).append("(");
+ TALValueCodegen.generateValueAccess(initExpr,
+ init.getFunctionCallArgs().get(0).getValue(), genCtx);
+ initExpr.append(")");
+ } else if (init.getFunctionCallName() != null
+ && primitiveWrapper(genCtx.resolver.functionReturnType(init.getFunctionCallName())) != null) {
+ // A built-in returning a primitive has to be boxed here: the local is declared as a wrapper, and
+ // Javassist's compiler does not autobox on assignment, which the verifier rejects.
+ final Class<?> wrapper = primitiveWrapper(
+ genCtx.resolver.functionReturnType(init.getFunctionCallName()));
+ initExpr.append(wrapper.getSimpleName()).append(".valueOf(");
+ TALValueCodegen.generateValueAccess(initExpr, init, genCtx);
+ initExpr.append(")");
+ resolvedType = wrapper;
+ } else {
+ // General value access — type inferred from lastResolvedType
+ TALValueCodegen.generateValueAccess(initExpr, init, genCtx);
+ resolvedType = genCtx.lastResolvedType != null
+ ? genCtx.lastResolvedType : Object.class;
+ // Box primitive types for local variable declarations
+ if (resolvedType.isPrimitive()) {
+ final String boxName = TALCodegenHelper.boxTypeName(resolvedType);
+ if (boxName != null) {
+ try {
+ resolvedType = Class.forName("java.lang." + boxName);
+ } catch (ClassNotFoundException ignored) {
+ // keep primitive
+ }
+ }
+ }
+ }
+
+ // Apply explicit type cast if specified (e.g., "as com.example.MyType")
+ final String castType = def.getCastType();
+ if (castType != null && !castType.isEmpty()) {
+ // Resolve the cast type — primitive wrapper names are handled,
+ // anything else is treated as a FQCN
+ final Class<?> castClass = resolveDefCastType(castType);
+ if (castClass != null) {
+ resolvedType = castClass;
+ }
+ }
+
+ // Register in local vars for later reference
+ genCtx.localVars.put(varName,
+ new TALLocalVar(javaVar, resolvedType));
+
+ // Emit declaration (placed at method top via localVarDecls) — skip if already declared
+ if (!alreadyDeclared) {
+ genCtx.localVarDecls.append(" ").append(resolvedType.getName())
+ .append(" ").append(javaVar).append(";\n");
+ genCtx.localVarLvtVars.add(new String[]{
+ javaVar, "L" + resolvedType.getName().replace('.', '/') + ";"
+ });
+ }
+
+ // Emit assignment in body (at the point where def appears).
+ // For built-in scalar casts the initialiser usually returns String
+ // or Object (e.g. tag() returns String), so a plain Java cast would
+ // throw ClassCastException at runtime. Route through the runtime
+ // helper which performs the proper conversion. FQCN casts still use
+ // a direct Java cast — those name a concrete type the caller knows
+ // the initialiser already produces.
+ sb.append(" ").append(javaVar).append(" = ");
+ if (castType != null && !castType.isEmpty()) {
+ final String conversion = scalarCastConversion(castType, initExpr);
+ if (conversion != null) {
+ sb.append(conversion);
+ } else {
+ sb.append("(").append(resolvedType.getName()).append(") ").append(initExpr);
+ }
+ } else {
+ sb.append(initExpr);
+ }
+ sb.append(";\n");
+ }
+
+ /**
+ * Render the boxed runtime-helper conversion for a scalar cast type
+ * (e.g. {@code Long.valueOf(h.toLong(<init>))}). Returns {@code null}
+ * for FQCN / unknown cast types so the caller can fall back to a
+ * direct Java cast.
+ */
+ private static String scalarCastConversion(final String castType,
+ final CharSequence init) {
+ switch (castType) {
+ case "String":
+ return "h.toStr(" + init + ")";
+ case "Long":
+ return "Long.valueOf(h.toLong(" + init + "))";
+ case "Integer":
+ return "Integer.valueOf(h.toInt(" + init + "))";
+ case "Double":
+ return "Double.valueOf(h.toDouble(" + init + "))";
+ case "Float":
+ return "Float.valueOf(h.toFloat(" + init + "))";
+ case "Boolean":
+ return "Boolean.valueOf(h.toBool(" + init + "))";
+ default:
+ return null;
+ }
+ }
+
+ /**
+ * Resolves a cast type string to a {@link Class}.
+ * Handles the four built-in type names ({@code String}, {@code Long},
+ * {@code Integer}, {@code Boolean}) and fully qualified class names.
+ */
+ private static Class<?> resolveDefCastType(final String castType) {
+ switch (castType) {
+ case "String":
+ return String.class;
+ case "Long":
+ return Long.class;
+ case "Integer":
+ return Integer.class;
+ case "Double":
+ return Double.class;
+ case "Float":
+ return Float.class;
+ case "Boolean":
+ return Boolean.class;
+ default:
+ try {
+ return Class.forName(castType);
+ } catch (ClassNotFoundException e) {
+ throw new IllegalArgumentException(
+ "def cast type not found on classpath: " + castType, e);
+ }
+ }
+ }
+
+ // ==================== Def variable chain codegen ====================
+
+ /**
+ * Generates typed method-chain access on a def variable.
+ * Uses reflection to resolve each method/field call and track types.
+ *
+ * @param sb output buffer
+ * @param localVar the def variable info (java var name + resolved type)
+ * @param chain the chain segments after the variable name
+ * @param genCtx codegen context
+ */
+ public static void generateDefVarChain(
+ final StringBuilder sb,
+ final TALLocalVar localVar,
+ final List<? extends TALValueAccessSegment> chain,
+ final TALGenCtx genCtx) {
+ if (chain.isEmpty()) {
+ sb.append(localVar.javaVarName);
+ genCtx.lastResolvedType = localVar.resolvedType;
+ return;
+ }
+
+ String prevExpr = localVar.javaVarName;
+ Class<?> currentType = localVar.resolvedType;
+ boolean canBeNull = true;
+
+ for (int i = 0; i < chain.size(); i++) {
+ final TALValueAccessSegment seg = chain.get(i);
+ final boolean isLast = i == chain.size() - 1;
+
+ if (seg instanceof TALMethodSegment) {
+ final TALMethodSegment ms =
+ (TALMethodSegment) seg;
+ final String methodName = ms.getName();
+
+ // Resolve method on currentType via reflection
+ final Method method =
+ resolveMethod(currentType, methodName, ms.getArguments());
+ if (method == null) {
+ throw new IllegalArgumentException(
+ "Cannot resolve method " + currentType.getSimpleName()
+ + "." + methodName + "() in def variable chain");
+ }
+ final Class<?> returnType = method.getReturnType();
+ final String args =
+ TALValueCodegen.generateMethodArgs(ms.getArguments(), genCtx);
+
+ if (ms.isSafeNav() && canBeNull) {
+ if (isLast && returnType.isPrimitive()) {
+ // Primitive return with null guard
+ final String boxName =
+ TALCodegenHelper.boxTypeName(returnType);
+ prevExpr = "(" + prevExpr + " == null ? null : "
+ + boxName + ".valueOf(" + prevExpr + "."
+ + methodName + "(" + args + ")))";
+ currentType = returnType;
+ } else {
+ prevExpr = "(" + prevExpr + " == null ? null : "
+ + prevExpr + "." + methodName + "(" + args + "))";
+ currentType = returnType;
+ canBeNull = true;
+ }
+ } else {
+ prevExpr = prevExpr + "." + methodName + "(" + args + ")";
+ currentType = returnType;
+ canBeNull = !returnType.isPrimitive();
+ }
+ } else if (seg instanceof TALFieldSegment) {
+ final TALFieldSegment fs =
+ (TALFieldSegment) seg;
+ final String fieldName = fs.getName();
+ // Try getter first
+ final String getterName = "get"
+ + Character.toUpperCase(fieldName.charAt(0))
+ + fieldName.substring(1);
+ Method getter = null;
+ try {
+ getter = currentType.getMethod(getterName);
+ } catch (NoSuchMethodException e) {
+ // Try direct field access name
+ try {
+ getter = currentType.getMethod(fieldName);
+ } catch (NoSuchMethodException e2) {
+ throw new IllegalArgumentException(
+ "Cannot resolve field/getter "
+ + currentType.getSimpleName()
+ + "." + fieldName + " in def variable chain");
+ }
+ }
+ final Class<?> returnType = getter.getReturnType();
+
+ if (fs.isSafeNav() && canBeNull) {
+ if (isLast && returnType.isPrimitive()) {
+ final String boxName =
+ TALCodegenHelper.boxTypeName(returnType);
+ prevExpr = "(" + prevExpr + " == null ? null : "
+ + boxName + ".valueOf(" + prevExpr + "."
+ + getter.getName() + "()))";
+ currentType = returnType;
+ } else {
+ prevExpr = "(" + prevExpr + " == null ? null : "
+ + prevExpr + "." + getter.getName() + "())";
+ currentType = returnType;
+ canBeNull = true;
+ }
+ } else {
+ prevExpr = prevExpr + "." + getter.getName() + "()";
+ currentType = returnType;
+ canBeNull = !returnType.isPrimitive();
+ }
+ } else if (seg instanceof TALIndexSegment) {
+ final int index = ((TALIndexSegment) seg).getIndex();
+ // Try get(int) method (e.g., JsonArray.get(int))
+ Method getMethod = null;
+ try {
+ getMethod = currentType.getMethod("get", int.class);
+ } catch (NoSuchMethodException e) {
+ throw new IllegalArgumentException(
+ "Cannot resolve index access on "
+ + currentType.getSimpleName()
+ + " in def variable chain");
+ }
+ final Class<?> returnType = getMethod.getReturnType();
+ if (canBeNull) {
+ prevExpr = "(" + prevExpr + " == null ? null : "
+ + prevExpr + ".get(" + index + "))";
+ } else {
+ prevExpr = prevExpr + ".get(" + index + ")";
+ }
+ currentType = returnType;
+ canBeNull = true;
+ }
+ }
+
+ genCtx.lastResolvedType = currentType;
+ sb.append(prevExpr);
+ }
+
+ /**
+ * Resolves a method on the given type by name, matching argument count.
+ * For methods with String arguments (like JsonObject.get(String)),
+ * prioritizes exact match by parameter types.
+ */
+ private static Method resolveMethod(
+ final Class<?> type, final String name,
+ final List<? extends TALFunctionArg> args) {
+ final int argCount = args != null ? args.size() : 0;
+ // Try exact match with common parameter types
+ if (argCount == 1) {
+ try {
+ return type.getMethod(name, String.class);
+ } catch (NoSuchMethodException ignored) {
+ // fall through
+ }
+ try {
+ return type.getMethod(name, int.class);
+ } catch (NoSuchMethodException ignored) {
+ // fall through
+ }
+ }
+ if (argCount == 0) {
+ try {
+ return type.getMethod(name);
+ } catch (NoSuchMethodException ignored) {
+ // fall through
+ }
+ }
+ // Fallback: find by name and arg count
+ for (final Method m : type.getMethods()) {
+ if (m.getName().equals(name)
+ && m.getParameterCount() == argCount) {
+ return m;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * @param type the static type a built-in declares
+ * @return the wrapper class to box it into, or null when the type is already a reference
+ */
+ private static Class<?> primitiveWrapper(final ExprType type) {
+ if (type == null) {
+ return null;
+ }
+ switch (type) {
+ case INT:
+ return Integer.class;
+ case LONG:
+ return Long.class;
+ case FLOAT:
+ return Float.class;
+ case DOUBLE:
+ return Double.class;
+ case BOOLEAN:
+ return Boolean.class;
+ default:
+ return null;
+ }
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALGenCtx.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALGenCtx.java
new file mode 100644
index 0000000000..ebd1b614ef
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALGenCtx.java
@@ -0,0 +1,155 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The state one rule's code generation carries: the resolved types, the private methods emitted so far, the local
+ * and cached-chain variables, and the channel {@link TALRootResolver#generateInputRootAccess} uses to report the
+ * static type and null checks of the chain it just emitted.
+ *
+ * <p>Shared by every DSL; what differs between them lives behind {@link #resolver}.
+ */
+public class TALGenCtx {
+ public final TALRootResolver resolver;
+ public final Class<?> inputType;
+ public final Class<?> outputType;
+ public final List<TALPrivateMethod> privateMethods = new ArrayList<>();
+ private final Map<String, Integer> methodCounts = new HashMap<>();
+
+ /**
+ * Rule's name, emitted as the first argument of every probe call site.
+ */
+ public String ruleName = "";
+
+ /**
+ * Set by the input-root codegen so a caller can specialize on a primitive leaf; cleared at the start of every
+ * value access.
+ */
+ public Class<?> lastResolvedType;
+ public String lastNullChecks;
+ public String lastRawChain;
+
+ /**
+ * Per-method chain variable caching: chain key to variable name, so the same chain accessed twice reuses one
+ * variable.
+ */
+ public final Map<String, String> protoVars = new HashMap<>();
+ public final List<String[]> protoLvtVars = new ArrayList<>();
+ public final StringBuilder protoVarDecls = new StringBuilder();
+ public int protoVarCounter;
+ public boolean usedProtoAccess;
+
+ /**
+ * Local variables from {@code def} statements, keyed by the name the rule chose. The declaration is hoisted to
+ * the top of the generated method, so a second {@code def} of one name is an assignment, not a new variable.
+ */
+ public final Map<String, TALLocalVar> localVars = new HashMap<>();
+ public final StringBuilder localVarDecls = new StringBuilder();
+ public final List<String[]> localVarLvtVars = new ArrayList<>();
+
+ /**
+ * The prefix every metric of this rule's file carries, from the file's {@code metricPrefix}.
+ */
+ public String metricPrefix;
+
+ /**
+ * Every metric the rule declares, including those inside {@code if} branches, collected so
+ * {@code MeterSystem.create} runs for each before the class is loaded.
+ */
+ public final List<TALMetricDeclaration> metricDeclarations = new ArrayList<>();
+
+ /**
+ * {@code def} variables that hold an entity, mapped to the {@code ScopeType} their constructor implies, so a
+ * {@code scope} naming one registers its metric under the right scope.
+ */
+ public final Map<String, String> entityScopeTypes = new HashMap<>();
+
+ private int localNameCounter;
+
+ public TALGenCtx(final TALRootResolver resolver, final Class<?> inputType, final Class<?> outputType) {
+ this.resolver = resolver;
+ this.inputType = inputType;
+ this.outputType = outputType;
+ }
+
+ /**
+ * @param prefix a short prefix naming what the variable holds
+ * @return a variable name unique within the generated class
+ */
+ public String nextLocalName(final String prefix) {
+ return prefix + localNameCounter++;
+ }
+
+ public String nextMethodName(final String prefix) {
+ final int count = methodCounts.merge(prefix, 1, Integer::sum);
+ return count == 1 ? "_" + prefix : "_" + prefix + "_" + count;
+ }
+
+ public void clearExtraLogResult() {
+ lastResolvedType = null;
+ lastNullChecks = null;
+ lastRawChain = null;
+ }
+
+ public void resetProtoVars() {
+ protoVars.clear();
+ protoLvtVars.clear();
+ protoVarDecls.setLength(0);
+ protoVarCounter = 0;
+ usedProtoAccess = false;
+ localVars.clear();
+ localVarDecls.setLength(0);
+ localVarLvtVars.clear();
+ }
+
+ public Object[] saveProtoVarState() {
+ return new Object[] {
+ new HashMap<>(protoVars),
+ new ArrayList<>(protoLvtVars),
+ protoVarDecls.toString(),
+ protoVarCounter,
+ usedProtoAccess,
+ new HashMap<>(localVars),
+ localVarDecls.toString(),
+ new ArrayList<>(localVarLvtVars)
+ };
+ }
+
+ @SuppressWarnings("unchecked")
+ public void restoreProtoVarState(final Object[] state) {
+ protoVars.clear();
+ protoVars.putAll((Map<String, String>) state[0]);
+ protoLvtVars.clear();
+ protoLvtVars.addAll((List<String[]>) state[1]);
+ protoVarDecls.setLength(0);
+ protoVarDecls.append((String) state[2]);
+ protoVarCounter = (Integer) state[3];
+ usedProtoAccess = (Boolean) state[4];
+ localVars.clear();
+ localVars.putAll((Map<String, TALLocalVar>) state[5]);
+ localVarDecls.setLength(0);
+ localVarDecls.append((String) state[6]);
+ localVarLvtVars.clear();
+ localVarLvtVars.addAll((List<String[]>) state[7]);
+ }
+}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALLocalVar.java
similarity index 55%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALLocalVar.java
index e3c3eedfc1..027384cd6d 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALLocalVar.java
@@ -13,24 +13,22 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * A local variable a {@code def} statement declared: the Java name the generated method uses, the type inferred
+ * from its initializer, and that type's JVM descriptor for the local-variable table.
+ */
+public class TALLocalVar {
+ public final String javaVarName;
+ public final Class<?> resolvedType;
+ public final String descriptor;
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+ public TALLocalVar(final String javaVarName, final Class<?> resolvedType) {
+ this.javaVarName = javaVarName;
+ this.resolvedType = resolvedType;
+ this.descriptor = "L" + resolvedType.getName().replace('.', '/') + ";";
+ }
}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricDeclaration.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricDeclaration.java
new file mode 100644
index 0000000000..e5d36d9629
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricDeclaration.java
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.Objects;
+
+/**
+ * One metric a rule declares: everything {@code MeterSystem.create} needs, collected at compile so the storage
+ * model is installed before a span arrives.
+ *
+ * <p>Two blocks declaring the same name with the same shape share one metric, which is how {@code if} branches
+ * feed one series; the same name with a different function or scope is a compile error.
+ */
+public final class TALMetricDeclaration {
+ public final String fullName;
+ public final String function;
+ public final String scopeType;
+ /**
+ * The name as the rule wrote it, without the file's prefix, for diagnostics.
+ */
+ public final String declaredName;
+
+ public TALMetricDeclaration(final String fullName, final String function,
+ final String scopeType, final String declaredName) {
+ this.fullName = fullName;
+ this.function = function;
+ this.scopeType = scopeType;
+ this.declaredName = declaredName;
+ }
+
+ @Override
+ public boolean equals(final Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (!(o instanceof TALMetricDeclaration)) {
+ return false;
+ }
+ final TALMetricDeclaration other = (TALMetricDeclaration) o;
+ return Objects.equals(fullName, other.fullName)
+ && Objects.equals(function, other.function)
+ && Objects.equals(scopeType, other.scopeType);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(fullName, function, scopeType);
+ }
+
+ @Override
+ public String toString() {
+ return fullName + "(" + function + ", " + scopeType + ")";
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricFunction.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricFunction.java
new file mode 100644
index 0000000000..7ff2cea56a
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALMetricFunction.java
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * The functions a {@code metrics {}} block may name, each mapping to a {@code MeterSystem} function and the
+ * value type that function accepts.
+ *
+ * <p>{@code cpm} is {@code sumPerMin} under the name the agent metrics use, because both compute
+ * {@code total / getDurationInMinute()}; a TAL metric named like an agent metric therefore holds the same number
+ * in the same unit.
+ */
+final class TALMetricFunction {
+ /**
+ * What the generated code has to build for the function to accept it.
+ */
+ enum Kind {
+ LONG, BOOLEAN, APDEX, HISTOGRAM, PERCENTILE, LABELED
+ }
+
+ private static final Map<String, TALMetricFunction> REGISTRY = new HashMap<>();
+
+ static {
+ register("cpm", "sumPerMin", Kind.LONG, "java.lang.Long");
+ register("sumPerMin", "sumPerMin", Kind.LONG, "java.lang.Long");
+ register("sum", "sum", Kind.LONG, "java.lang.Long");
+ register("avg", "avg", Kind.LONG, "java.lang.Long");
+ register("max", "max", Kind.LONG, "java.lang.Long");
+ register("min", "min", Kind.LONG, "java.lang.Long");
+ register("latest", "latest", Kind.LONG, "java.lang.Long");
+ register("percent", "percent", Kind.BOOLEAN, "java.lang.Boolean");
+ register("apdex", "apdex", Kind.APDEX,
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.ApdexArgument");
+ register("histogram", "sumHistogram", Kind.HISTOGRAM,
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.BucketedValues");
+ register("percentile", "sumHistogramPercentile", Kind.PERCENTILE,
+ "org.apache.skywalking.oap.server.core.analysis.meter.function.PercentileArgument");
+ register("sumLabeled", "sumLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ register("avgLabeled", "avgLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ register("maxLabeled", "maxLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ register("minLabeled", "minLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ register("latestLabeled", "latestLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ register("sumPerMinLabeled", "sumPerMinLabeled", Kind.LABELED,
+ "org.apache.skywalking.oap.server.core.analysis.metrics.DataTable");
+ }
+
+ final String meterFunction;
+ final Kind kind;
+ final String valueClass;
+
+ private TALMetricFunction(final String meterFunction, final Kind kind, final String valueClass) {
+ this.meterFunction = meterFunction;
+ this.kind = kind;
+ this.valueClass = valueClass;
+ }
+
+ private static void register(final String name, final String meterFunction,
+ final Kind kind, final String valueClass) {
+ REGISTRY.put(name, new TALMetricFunction(meterFunction, kind, valueClass));
+ }
+
+ /**
+ * @param name the function a rule named
+ * @return its definition
+ * @throws IllegalArgumentException when no function goes by that name
+ */
+ static TALMetricFunction of(final String name) {
+ if (name == null) {
+ throw new IllegalArgumentException("a metrics block needs a function");
+ }
+ final TALMetricFunction function = REGISTRY.get(name);
+ if (function == null) {
+ throw new IllegalArgumentException(
+ "unknown metrics function '" + name + "'; known functions are " + REGISTRY.keySet());
+ }
+ return function;
+ }
+}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALPrivateMethod.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALPrivateMethod.java
index e3c3eedfc1..517df037e7 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALPrivateMethod.java
@@ -13,24 +13,20 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * One private method the generator emits beside {@code execute}, with the local-variable table entries that make
+ * it debuggable.
+ */
+public class TALPrivateMethod {
+ public final String source;
+ public final String[][] lvtVars;
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+ public TALPrivateMethod(final String source, final String[][] lvtVars) {
+ this.source = source;
+ this.lvtVars = lvtVars;
+ }
}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALRootResolver.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALRootResolver.java
new file mode 100644
index 0000000000..c7461ae38d
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALRootResolver.java
@@ -0,0 +1,98 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.List;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessSegment;
+
+/**
+ * Everything the shared expression codegen cannot know: a DSL's roots and its built-in functions.
+ *
+ * <p>{@link TALValueCodegen} owns arithmetic, comparison, casts, literals, safe navigation, {@code def} variables
+ * and reflective getter chains, all of which read the same in every DSL. What differs is the handful of names a
+ * rule starts an expression with, and that is what this supplies: the {@code span} and {@code meta} roots,
+ * {@code attr()} and the rest of TAL's span vocabulary, and the entity constructors.
+ */
+public interface TALRootResolver {
+ /**
+ * Emit a call to one of this DSL's built-in functions.
+ *
+ * @param sb the buffer the generated Java source is appended to
+ * @param value the expression, whose {@code functionCallName} names the built-in
+ * @param ctx the generation context
+ * @return true when the name was one of this DSL's built-ins and code was emitted, false to let the shared
+ * codegen continue looking
+ */
+ boolean generateFunctionCall(StringBuilder sb, TALValueAccess value, TALGenCtx ctx);
+
+ /**
+ * Emit a reference to a static helper the language exposes. TAL has none today; the hook exists because the
+ * expression engine dispatches on it.
+ *
+ * @param sb the buffer the generated Java source is appended to
+ * @param value the expression, for which {@link TALValueAccess#isStaticRef()} is true
+ * @param ctx the generation context
+ * @return true when code was emitted
+ */
+ default boolean generateStaticRefAccess(final StringBuilder sb, final TALValueAccess value,
+ final TALGenCtx ctx) {
+ return false;
+ }
+
+ /**
+ * Emit a chain rooted at the metadata root, {@code meta.*}.
+ *
+ * @param sb the buffer the generated Java source is appended to
+ * @param chain the accesses applied to the root
+ * @param ctx the generation context
+ */
+ void generateMetaRootAccess(StringBuilder sb, List<? extends TALValueAccessSegment> chain, TALGenCtx ctx);
+
+ /**
+ * Emit a chain rooted at the input root, {@code span.*}, by walking it reflectively through
+ * {@link TALValueCodegen#generateTypedChainAccess} against the rule's declared input type.
+ *
+ * @param sb the buffer the generated Java source is appended to
+ * @param chain the accesses applied to the root
+ * @param ctx the generation context
+ */
+ void generateInputRootAccess(StringBuilder sb, List<? extends TALValueAccessSegment> chain, TALGenCtx ctx);
+
+ /**
+ * @param functionName the built-in being called
+ * @return the type that built-in returns, so arithmetic and comparisons around it are typed rather than
+ * falling back to string concatenation; null when the DSL does not know the name
+ */
+ default ExprType functionReturnType(final String functionName) {
+ return null;
+ }
+
+ /**
+ * @return whether the input root resolves against {@link TALGenCtx#inputType}, so a chain on it can be walked
+ * by reflection at compile time. A span always has a declared input type, so this is true whenever the rule
+ * compiled with one.
+ */
+ boolean isTypedInputActive();
+
+ /**
+ * @return a short description of the compile context, such as the active parser and input type, quoted in the
+ * diagnostic raised when no codegen path matches an expression
+ */
+ String describeContext();
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptModel.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptModel.java
new file mode 100644
index 0000000000..83194297ee
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptModel.java
@@ -0,0 +1,665 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import lombok.Getter;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.BinaryOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.CompareOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.LogicalOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALBoolConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALComparisonCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALDefStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALExprCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFieldSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionArg;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionCallConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALIndexSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALLogicalCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALMethodSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNotCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNullConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNumberConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALStringConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessSegment;
+
+/**
+ * The immutable parse tree of one TAL rule, produced by {@link TALScriptParser} and read by
+ * {@link TALClassGenerator}.
+ *
+ * <p>The expression types implement the {@code model} interfaces, which is the view
+ * {@link TALValueCodegen} compiles against; the statement types are TAL's own and have no counterpart there.
+ */
+@Getter
+public final class TALScriptModel {
+ private final List<FilterStatement> statements;
+
+ public TALScriptModel(final List<FilterStatement> statements) {
+ this.statements = Collections.unmodifiableList(statements);
+ }
+
+ // ==================== Statements ====================
+
+ /**
+ * Anything that can appear directly inside {@code filter { }}.
+ */
+ public interface FilterStatement {
+ }
+
+ /**
+ * Anything that can appear inside {@code extractor { }}.
+ */
+ public interface ExtractorStatement {
+ }
+
+ /**
+ * Anything that can appear inside {@code sink { }} or {@code persist { }}. The two blocks take the same
+ * statements and differ only in what they decide: the record, or the span.
+ */
+ public interface VoteStatement {
+ }
+
+ /**
+ * {@code abort {}} — stop the rule for this span. Legal at filter level and inside every block.
+ */
+ public static final class AbortStatement
+ implements FilterStatement, ExtractorStatement, VoteStatement {
+ }
+
+ @Getter
+ public static final class DefStatement
+ implements FilterStatement, ExtractorStatement, TALDefStatement {
+ private final String varName;
+ private final ValueAccess initializer;
+ private final String castType;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public DefStatement(final String varName, final ValueAccess initializer, final String castType) {
+ this.varName = varName;
+ this.initializer = initializer;
+ this.castType = castType;
+ }
+
+ public DefStatement withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ @Getter
+ public static final class ExtractorBlock implements FilterStatement {
+ private final List<ExtractorStatement> statements;
+
+ public ExtractorBlock(final List<ExtractorStatement> statements) {
+ this.statements = Collections.unmodifiableList(statements);
+ }
+ }
+
+ /**
+ * The standard identity fields an extractor may overwrite on {@code meta}, which are also the record's
+ * standard fields when the rule declares an {@code outputType}.
+ */
+ public enum FieldType {
+ SERVICE, INSTANCE, ENDPOINT, LAYER
+ }
+
+ @Getter
+ public static final class FieldAssignment implements ExtractorStatement, FilterStatement {
+ private final FieldType fieldType;
+ private final ValueAccess value;
+ private final String castType;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public FieldAssignment(final FieldType fieldType, final ValueAccess value, final String castType) {
+ this.fieldType = fieldType;
+ this.value = value;
+ this.castType = castType;
+ }
+
+ public FieldAssignment withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ /**
+ * A statement whose name is not a keyword: it sets a field on the rule's {@code outputType}, validated
+ * against a setter at compile time.
+ */
+ @Getter
+ public static final class OutputFieldAssignment implements ExtractorStatement, FilterStatement {
+ private final String fieldName;
+ private final ValueAccess value;
+ private final String castType;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public OutputFieldAssignment(final String fieldName, final ValueAccess value, final String castType) {
+ this.fieldName = fieldName;
+ this.value = value;
+ this.castType = castType;
+ }
+
+ public OutputFieldAssignment withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ /**
+ * {@code alias <address>} — register the address as an alias of the span's service; the runtime helper's
+ * {@code alias} says what that means.
+ */
+ @Getter
+ public static final class AliasStatement implements ExtractorStatement, FilterStatement {
+ private final ValueAccess address;
+ private final String castType;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public AliasStatement(final ValueAccess address, final String castType) {
+ this.address = address;
+ this.castType = castType;
+ }
+
+ public AliasStatement withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ /**
+ * {@code tag 'key': value} — appended to the persisted span as a string attribute.
+ */
+ @Getter
+ public static final class TagAssignment implements ExtractorStatement, FilterStatement {
+ private final Map<String, TagValue> tags;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public TagAssignment(final Map<String, TagValue> tags) {
+ this.tags = Collections.unmodifiableMap(tags);
+ }
+
+ public TagAssignment withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ @Getter
+ public static final class TagValue {
+ private final ValueAccess value;
+ private final String castType;
+
+ public TagValue(final ValueAccess value, final String castType) {
+ this.value = value;
+ this.castType = castType;
+ }
+ }
+
+ /**
+ * One {@code metrics { }} block: a metric name, the entity it lands on, the function that aggregates it and
+ * the observation. {@code name} and {@code function} are literals and {@code scope}'s constructor is known at
+ * compile time, so the compiler knows every metric a rule declares before a span arrives.
+ */
+ @Getter
+ public static final class MetricsBlock implements ExtractorStatement, FilterStatement {
+ private final String name;
+ private final ValueAccess scope;
+ private final String function;
+ private final ValueAccess value;
+ /**
+ * Required by {@code percent}, forbidden elsewhere: the span counts as a match when this holds.
+ */
+ private final Condition match;
+ /**
+ * Required by {@code apdex}, forbidden elsewhere: the span counts as successful when this holds.
+ */
+ private final Condition status;
+ private final Map<String, TagValue> labels;
+ /**
+ * Ascending bucket bounds, in the unit of {@code value}; required by {@code histogram} and
+ * {@code percentile}. Kept as the literal text so the compiler preserves the declared numeric type.
+ */
+ private final List<String> buckets;
+ private final List<String> ranks;
+ private final ValueAccess timestamp;
+ private int sourceLine;
+ private String sourceText = "";
+
+ public MetricsBlock(final String name,
+ final ValueAccess scope,
+ final String function,
+ final ValueAccess value,
+ final Condition match,
+ final Condition status,
+ final Map<String, TagValue> labels,
+ final List<String> buckets,
+ final List<String> ranks,
+ final ValueAccess timestamp) {
+ this.name = name;
+ this.scope = scope;
+ this.function = function;
+ this.value = value;
+ this.match = match;
+ this.status = status;
+ this.labels = labels == null ? Collections.emptyMap() : Collections.unmodifiableMap(labels);
+ this.buckets = buckets == null ? Collections.emptyList() : Collections.unmodifiableList(buckets);
+ this.ranks = ranks == null ? Collections.emptyList() : Collections.unmodifiableList(ranks);
+ this.timestamp = timestamp;
+ }
+
+ public MetricsBlock withSource(final int line, final String text) {
+ this.sourceLine = line;
+ this.sourceText = text == null ? "" : text;
+ return this;
+ }
+ }
+
+ /**
+ * {@code sink { }} — what happens to the record the rule built. A rule without an {@code outputType} has no
+ * record, so a sink in it is a compile error rather than a silent no-op.
+ */
+ @Getter
+ public static final class SinkBlock implements FilterStatement {
+ private final List<VoteStatement> statements;
+
+ public SinkBlock(final List<VoteStatement> statements) {
+ this.statements = Collections.unmodifiableList(statements);
+ }
+ }
+
+ /**
+ * {@code persist { }} — the span's own fate. A rule without this block abstains.
+ */
+ @Getter
+ public static final class PersistBlock implements FilterStatement {
+ private final List<VoteStatement> statements;
+
+ public PersistBlock(final List<VoteStatement> statements) {
+ this.statements = Collections.unmodifiableList(statements);
+ }
+ }
+
+ @Getter
+ public static final class SamplerBlock implements VoteStatement, FilterStatement {
+ private final List<SamplerContent> contents;
+
+ public SamplerBlock(final List<SamplerContent> contents) {
+ this.contents = Collections.unmodifiableList(contents);
+ }
+ }
+
+ public interface SamplerContent {
+ }
+
+ @Getter
+ public static final class RateLimitBlock implements SamplerContent {
+ private final String id;
+ private final List<InterpolationPart> idParts;
+ private final int rpm;
+
+ public RateLimitBlock(final String id, final List<InterpolationPart> idParts, final int rpm) {
+ this.id = id;
+ this.idParts = idParts == null ? Collections.emptyList() : Collections.unmodifiableList(idParts);
+ this.rpm = rpm;
+ }
+
+ /**
+ * @return whether the id contains {@code ${...}} placeholders and has to be built per span
+ */
+ public boolean isIdInterpolated() {
+ return !idParts.isEmpty();
+ }
+ }
+
+ @Getter
+ public static final class InterpolationPart {
+ private final String text;
+ private final ValueAccess expression;
+
+ private InterpolationPart(final String text, final ValueAccess expression) {
+ this.text = text;
+ this.expression = expression;
+ }
+
+ public static InterpolationPart ofLiteral(final String text) {
+ return new InterpolationPart(text, null);
+ }
+
+ public static InterpolationPart ofExpression(final ValueAccess expr) {
+ return new InterpolationPart(null, expr);
+ }
+
+ public boolean isLiteral() {
+ return expression == null;
+ }
+ }
+
+ /**
+ * Vote keep regardless of the samplers in the same rule, and, in a {@code persist} block, ask the forward to
+ * skip the receiver's trace-id head sampling for this span.
+ */
+ public static final class EnforcerStatement implements VoteStatement, FilterStatement {
+ }
+
+ public static final class DropperStatement implements VoteStatement, FilterStatement {
+ }
+
+ /**
+ * {@code if / else if / else}. An {@code else if} chain is nested: the else branch of one block holds the
+ * next, so the generator emits one shape rather than two.
+ */
+ @Getter
+ public static final class IfBlock
+ implements FilterStatement, ExtractorStatement, VoteStatement, SamplerContent {
+ private final Condition condition;
+ private final List<FilterStatement> thenStatements;
+ private final List<FilterStatement> elseStatements;
+
+ public IfBlock(final Condition condition,
+ final List<FilterStatement> thenStatements,
+ final List<FilterStatement> elseStatements) {
+ this.condition = condition;
+ this.thenStatements = Collections.unmodifiableList(thenStatements);
+ this.elseStatements = elseStatements == null
+ ? Collections.emptyList() : Collections.unmodifiableList(elseStatements);
+ }
+ }
+
+ // ==================== Conditions ====================
+
+ public interface Condition extends TALCondition {
+ }
+
+ @Getter
+ public static final class ComparisonCondition implements Condition, TALComparisonCondition {
+ private final ValueAccess left;
+ private final String leftCast;
+ private final CompareOp op;
+ private final ConditionValue right;
+
+ public ComparisonCondition(final ValueAccess left,
+ final String leftCast,
+ final CompareOp op,
+ final ConditionValue right) {
+ this.left = left;
+ this.leftCast = leftCast;
+ this.op = op;
+ this.right = right;
+ }
+ }
+
+ @Getter
+ public static final class LogicalCondition implements Condition, TALLogicalCondition {
+ private final Condition left;
+ private final LogicalOp op;
+ private final Condition right;
+
+ public LogicalCondition(final Condition left, final LogicalOp op, final Condition right) {
+ this.left = left;
+ this.op = op;
+ this.right = right;
+ }
+ }
+
+ @Getter
+ public static final class NotCondition implements Condition, TALNotCondition {
+ private final Condition inner;
+
+ public NotCondition(final Condition inner) {
+ this.inner = inner;
+ }
+ }
+
+ @Getter
+ public static final class ExprCondition implements Condition, TALExprCondition {
+ private final ValueAccess expr;
+ private final String castType;
+
+ public ExprCondition(final ValueAccess expr, final String castType) {
+ this.expr = expr;
+ this.castType = castType;
+ }
+ }
+
+ // ==================== Condition values ====================
+
+ public interface ConditionValue extends TALConditionValue {
+ }
+
+ @Getter
+ public static final class StringConditionValue implements ConditionValue, TALStringConditionValue {
+ private final String value;
+
+ public StringConditionValue(final String value) {
+ this.value = value;
+ }
+ }
+
+ @Getter
+ public static final class NumberConditionValue implements ConditionValue, TALNumberConditionValue {
+ private final double value;
+ /**
+ * The literal exactly as the rule wrote it, which is what preserves the declared numeric type.
+ */
+ private final String literal;
+
+ public NumberConditionValue(final double value) {
+ this(value, null);
+ }
+
+ public NumberConditionValue(final double value, final String literal) {
+ this.value = value;
+ this.literal = literal;
+ }
+ }
+
+ @Getter
+ public static final class BoolConditionValue implements ConditionValue, TALBoolConditionValue {
+ private final boolean value;
+
+ public BoolConditionValue(final boolean value) {
+ this.value = value;
+ }
+ }
+
+ public static final class NullConditionValue implements ConditionValue, TALNullConditionValue {
+ }
+
+ @Getter
+ public static final class ValueAccessConditionValue implements ConditionValue, TALValueAccessConditionValue {
+ private final ValueAccess value;
+ private final String castType;
+
+ public ValueAccessConditionValue(final ValueAccess value, final String castType) {
+ this.value = value;
+ this.castType = castType;
+ }
+ }
+
+ @Getter
+ public static final class FunctionCallConditionValue implements ConditionValue, TALFunctionCallConditionValue {
+ private final String functionName;
+ private final List<String> arguments;
+
+ public FunctionCallConditionValue(final String functionName, final List<String> arguments) {
+ this.functionName = functionName;
+ this.arguments = Collections.unmodifiableList(arguments);
+ }
+ }
+
+ // ==================== Value access ====================
+
+ @Getter
+ public static final class ValueAccess implements TALValueAccess {
+ private final List<String> segments;
+ private final boolean spanRef;
+ private final boolean metaRef;
+ private final boolean stringLiteral;
+ private final boolean numberLiteral;
+ private final List<ValueAccessSegment> chain;
+ private final String functionCallName;
+ private final List<FunctionArg> functionCallArgs;
+ private final List<ValueAccess> concatParts;
+ private final List<BinaryOp> concatOps;
+ private final ValueAccess parenInner;
+ private final String parenCast;
+
+ public ValueAccess(final List<String> segments,
+ final boolean spanRef,
+ final boolean metaRef,
+ final List<ValueAccessSegment> chain) {
+ this(segments, spanRef, metaRef, false, false, chain, null,
+ Collections.emptyList(), Collections.emptyList(), Collections.emptyList(), null, null);
+ }
+
+ public ValueAccess(final List<String> segments,
+ final boolean spanRef,
+ final boolean metaRef,
+ final boolean stringLiteral,
+ final boolean numberLiteral,
+ final List<ValueAccessSegment> chain,
+ final String functionCallName,
+ final List<FunctionArg> functionCallArgs) {
+ this(segments, spanRef, metaRef, stringLiteral, numberLiteral, chain,
+ functionCallName, functionCallArgs,
+ Collections.emptyList(), Collections.emptyList(), null, null);
+ }
+
+ public ValueAccess(final List<String> segments,
+ final boolean spanRef,
+ final boolean metaRef,
+ final boolean stringLiteral,
+ final boolean numberLiteral,
+ final List<ValueAccessSegment> chain,
+ final String functionCallName,
+ final List<FunctionArg> functionCallArgs,
+ final List<ValueAccess> concatParts,
+ final List<BinaryOp> concatOps,
+ final ValueAccess parenInner,
+ final String parenCast) {
+ this.segments = Collections.unmodifiableList(segments);
+ this.spanRef = spanRef;
+ this.metaRef = metaRef;
+ this.stringLiteral = stringLiteral;
+ this.numberLiteral = numberLiteral;
+ this.chain = chain != null ? Collections.unmodifiableList(chain) : Collections.emptyList();
+ this.functionCallName = functionCallName;
+ this.functionCallArgs = functionCallArgs != null
+ ? Collections.unmodifiableList(functionCallArgs) : Collections.emptyList();
+ this.concatParts = concatParts != null
+ ? Collections.unmodifiableList(concatParts) : Collections.emptyList();
+ this.concatOps = concatOps != null
+ ? Collections.unmodifiableList(concatOps) : Collections.emptyList();
+ this.parenInner = parenInner;
+ this.parenCast = parenCast;
+ }
+
+ @Override
+ public String toPathString() {
+ return String.join(".", segments);
+ }
+
+ /**
+ * TAL's input root is {@code span}, the wire object the rule declared as its input type.
+ */
+ @Override
+ public boolean isInputRef() {
+ return spanRef;
+ }
+
+ /**
+ * TAL's metadata root is {@code meta}.
+ */
+ @Override
+ public boolean isMetaRef() {
+ return metaRef;
+ }
+
+ /**
+ * TAL has no static helper root; its entity constructors are ordinary function calls.
+ */
+ @Override
+ public boolean isStaticRef() {
+ return false;
+ }
+ }
+
+ @Getter
+ public static final class FunctionArg implements TALFunctionArg {
+ private final ValueAccess value;
+ private final String castType;
+
+ public FunctionArg(final ValueAccess value, final String castType) {
+ this.value = value;
+ this.castType = castType;
+ }
+ }
+
+ public interface ValueAccessSegment extends TALValueAccessSegment {
+ }
+
+ @Getter
+ public static final class FieldSegment implements ValueAccessSegment, TALFieldSegment {
+ private final String name;
+ private final boolean safeNav;
+
+ public FieldSegment(final String name, final boolean safeNav) {
+ this.name = name;
+ this.safeNav = safeNav;
+ }
+ }
+
+ @Getter
+ public static final class MethodSegment implements ValueAccessSegment, TALMethodSegment {
+ private final String name;
+ private final List<FunctionArg> arguments;
+ private final boolean safeNav;
+
+ public MethodSegment(final String name, final List<FunctionArg> arguments, final boolean safeNav) {
+ this.name = name;
+ this.arguments = arguments != null
+ ? Collections.unmodifiableList(arguments) : Collections.emptyList();
+ this.safeNav = safeNav;
+ }
+ }
+
+ @Getter
+ public static final class IndexSegment implements ValueAccessSegment, TALIndexSegment {
+ private final int index;
+
+ public IndexSegment(final int index) {
+ this.index = index;
+ }
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptParser.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptParser.java
new file mode 100644
index 0000000000..9fe0f055c1
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALScriptParser.java
@@ -0,0 +1,900 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import org.antlr.v4.runtime.BaseErrorListener;
+import org.antlr.v4.runtime.CharStreams;
+import org.antlr.v4.runtime.CommonTokenStream;
+import org.antlr.v4.runtime.ParserRuleContext;
+import org.antlr.v4.runtime.RecognitionException;
+import org.antlr.v4.runtime.Recognizer;
+import org.antlr.v4.runtime.misc.Interval;
+import org.antlr.v4.runtime.tree.ParseTree;
+import org.antlr.v4.runtime.tree.TerminalNode;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.AbortStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.Condition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.DefStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.DropperStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.EnforcerStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.ExtractorBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.ExtractorStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.FieldSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.FieldType;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.FilterStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.IfBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.IndexSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.InterpolationPart;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.MetricsBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.PersistBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.RateLimitBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.SamplerBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.SamplerContent;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.SinkBlock;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.TagValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.ValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.ValueAccessSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.TALScriptModel.VoteStatement;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.BinaryOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.CompareOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.LogicalOp;
+import org.apache.skywalking.tal.rt.grammar.TALLexer;
+import org.apache.skywalking.tal.rt.grammar.TALParser;
+
+/**
+ * Parses a TAL rule's DSL text into the immutable {@link TALScriptModel} the generator compiles.
+ *
+ * <p>Sibling implementation: {@code LALScriptParser} in {@code log-analyzer} does the same for LAL over its own
+ * grammar. Separate copies by design; see {@link TALValueCodegen}.
+ */
+public final class TALScriptParser {
+
+ private TALScriptParser() {
+ }
+
+ public static TALScriptModel parse(final String dsl) {
+ final TALLexer lexer = new TALLexer(CharStreams.fromString(dsl));
+ final CommonTokenStream tokens = new CommonTokenStream(lexer);
+ final TALParser parser = new TALParser(tokens);
+
+ final List<String> errors = new ArrayList<>();
+ parser.removeErrorListeners();
+ parser.addErrorListener(new BaseErrorListener() {
+ @Override
+ public void syntaxError(final Recognizer<?, ?> recognizer,
+ final Object offendingSymbol,
+ final int line,
+ final int charPositionInLine,
+ final String msg,
+ final RecognitionException e) {
+ errors.add(line + ":" + charPositionInLine + " " + msg);
+ }
+ });
+
+ final TALParser.RootContext tree = parser.root();
+ if (!errors.isEmpty()) {
+ throw new IllegalArgumentException(
+ "TAL script parsing failed: " + String.join("; ", errors)
+ + " in script: " + truncate(dsl, 200));
+ }
+
+ return new TALScriptModel(visitFilterContent(tree.filterBlock().filterContent()));
+ }
+
+ // ==================== Filter content ====================
+
+ private static List<FilterStatement> visitFilterContent(final TALParser.FilterContentContext ctx) {
+ final List<FilterStatement> stmts = new ArrayList<>();
+ for (final TALParser.FilterStatementContext fsc : ctx.filterStatement()) {
+ stmts.add(visitFilterStatement(fsc));
+ }
+ return stmts;
+ }
+
+ private static FilterStatement visitFilterStatement(final TALParser.FilterStatementContext ctx) {
+ if (ctx.extractorBlock() != null) {
+ return visitExtractorBlock(ctx.extractorBlock());
+ }
+ if (ctx.sinkBlock() != null) {
+ return visitSinkBlock(ctx.sinkBlock());
+ }
+ if (ctx.persistBlock() != null) {
+ return visitPersistBlock(ctx.persistBlock());
+ }
+ if (ctx.abortBlock() != null) {
+ return new AbortStatement();
+ }
+ if (ctx.defStatement() != null) {
+ return visitDefStatement(ctx.defStatement());
+ }
+ if (ctx.aliasStatement() != null) {
+ return visitAliasStatement(ctx.aliasStatement())
+ .withSource(ctx.getStart().getLine(), rawTextOf(ctx));
+ }
+ return visitIfStatement(ctx.ifStatement());
+ }
+
+ // ==================== Extractor block ====================
+
+ private static ExtractorBlock visitExtractorBlock(final TALParser.ExtractorBlockContext ctx) {
+ final List<ExtractorStatement> stmts = new ArrayList<>();
+ for (final TALParser.ExtractorStatementContext esc : ctx.extractorContent().extractorStatement()) {
+ stmts.add(visitExtractorStatement(esc));
+ }
+ return new ExtractorBlock(stmts);
+ }
+
+ private static ExtractorStatement visitExtractorStatement(final TALParser.ExtractorStatementContext ctx) {
+ // Capture (line, raw text) once at the statement boundary so every node below carries the same
+ // source-origin pair; dsl-debugging's per-line probe reads them back at codegen.
+ final int sourceLine = ctx.getStart().getLine();
+ final String sourceText = rawTextOf(ctx);
+
+ if (ctx.defStatement() != null) {
+ return visitDefStatement(ctx.defStatement()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.serviceStatement() != null) {
+ return visitFieldAssignment(FieldType.SERVICE, ctx.serviceStatement().valueAccess(),
+ ctx.serviceStatement().typeCast()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.instanceStatement() != null) {
+ return visitFieldAssignment(FieldType.INSTANCE, ctx.instanceStatement().valueAccess(),
+ ctx.instanceStatement().typeCast()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.endpointStatement() != null) {
+ return visitFieldAssignment(FieldType.ENDPOINT, ctx.endpointStatement().valueAccess(),
+ ctx.endpointStatement().typeCast()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.layerStatement() != null) {
+ return visitFieldAssignment(FieldType.LAYER, ctx.layerStatement().valueAccess(),
+ ctx.layerStatement().typeCast()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.tagStatement() != null) {
+ return visitTagStatement(ctx.tagStatement()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.aliasStatement() != null) {
+ return visitAliasStatement(ctx.aliasStatement()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.metricsBlock() != null) {
+ return visitMetricsBlock(ctx.metricsBlock()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.abortBlock() != null) {
+ return new AbortStatement();
+ }
+ if (ctx.outputFieldStatement() != null) {
+ return visitOutputFieldStatement(ctx.outputFieldStatement()).withSource(sourceLine, sourceText);
+ }
+ if (ctx.ifStatement() != null) {
+ return visitIfStatement(ctx.ifStatement());
+ }
+ // Every alternative of the grammar's extractorStatement rule has a branch above; falling through means a
+ // grammar change landed without one, and a named error beats a NullPointerException in the next visitor.
+ throw new IllegalArgumentException(
+ "Unsupported extractor statement in TAL rule at line " + sourceLine + ": " + sourceText);
+ }
+
+ /**
+ * Verbatim source text of a rule context, pulled from the input stream rather than re-concatenated from
+ * tokens, so whitespace inside the statement survives for the debugging UI.
+ */
+ private static String rawTextOf(final ParserRuleContext ctx) {
+ if (ctx.getStart() == null || ctx.getStop() == null) {
+ return "";
+ }
+ return ctx.getStart().getInputStream().getText(
+ Interval.of(ctx.getStart().getStartIndex(), ctx.getStop().getStopIndex()));
+ }
+
+ private static TALScriptModel.FieldAssignment visitFieldAssignment(
+ final FieldType type,
+ final TALParser.ValueAccessContext vaCtx,
+ final TALParser.TypeCastContext tcCtx) {
+ return new TALScriptModel.FieldAssignment(type, visitValueAccess(vaCtx), extractCastType(tcCtx));
+ }
+
+ private static TALScriptModel.OutputFieldAssignment visitOutputFieldStatement(
+ final TALParser.OutputFieldStatementContext ctx) {
+ return new TALScriptModel.OutputFieldAssignment(
+ ctx.anyIdentifier().getText(),
+ visitValueAccess(ctx.valueAccess()),
+ extractCastType(ctx.typeCast()));
+ }
+
+ private static DefStatement visitDefStatement(final TALParser.DefStatementContext ctx) {
+ return new DefStatement(
+ ctx.IDENTIFIER().getText(),
+ visitValueAccess(ctx.valueAccess()),
+ extractCastType(ctx.typeCast()));
+ }
+
+ private static TALScriptModel.AliasStatement visitAliasStatement(final TALParser.AliasStatementContext ctx) {
+ return new TALScriptModel.AliasStatement(
+ visitValueAccess(ctx.valueAccess()), extractCastType(ctx.typeCast()));
+ }
+
+ private static TALScriptModel.TagAssignment visitTagStatement(final TALParser.TagStatementContext ctx) {
+ final Map<String, TagValue> tags = new LinkedHashMap<>();
+ if (ctx.tagMap() != null) {
+ final TALParser.TagMapContext map = ctx.tagMap();
+ for (int i = 0; i < map.anyIdentifier().size(); i++) {
+ tags.put(
+ stripQuotes(map.anyIdentifier(i).getText()),
+ new TagValue(visitValueAccess(map.valueAccess(i)), extractCastType(map.typeCast(i))));
+ }
+ } else {
+ tags.put(
+ stripQuotes(ctx.STRING().getText()),
+ new TagValue(visitValueAccess(ctx.valueAccess()), extractCastType(ctx.typeCast())));
+ }
+ return new TALScriptModel.TagAssignment(tags);
+ }
+
+ // ==================== Metrics block ====================
+
+ private static MetricsBlock visitMetricsBlock(final TALParser.MetricsBlockContext ctx) {
+ String name = null;
+ ValueAccess scope = null;
+ String function = null;
+ ValueAccess value = null;
+ Condition match = null;
+ Condition status = null;
+ final Map<String, TagValue> labels = new LinkedHashMap<>();
+ List<String> buckets = null;
+ List<String> ranks = null;
+ ValueAccess timestamp = null;
+
+ for (final TALParser.MetricsStatementContext msc : ctx.metricsContent().metricsStatement()) {
+ if (msc.metricsNameStatement() != null) {
+ name = resolveValueAsString(msc.metricsNameStatement().valueAccess());
+ } else if (msc.metricsScopeStatement() != null) {
+ scope = visitValueAccess(msc.metricsScopeStatement().valueAccess());
+ } else if (msc.metricsFunctionStatement() != null) {
+ function = msc.metricsFunctionStatement().anyIdentifier().getText();
+ } else if (msc.metricsValueStatement() != null) {
+ value = visitValueAccess(msc.metricsValueStatement().valueAccess());
+ } else if (msc.metricsMatchStatement() != null) {
+ match = visitCondition(msc.metricsMatchStatement().condition());
+ } else if (msc.metricsStatusStatement() != null) {
+ status = visitCondition(msc.metricsStatusStatement().condition());
+ } else if (msc.metricsLabelsStatement() != null) {
+ for (final TALParser.LabelEntryContext lec : msc.metricsLabelsStatement().labelMap().labelEntry()) {
+ labels.put(
+ lec.anyIdentifier().getText(),
+ new TagValue(visitValueAccess(lec.valueAccess()), extractCastType(lec.typeCast())));
+ }
+ } else if (msc.metricsBucketsStatement() != null) {
+ buckets = numberListOf(msc.metricsBucketsStatement().numberList());
+ } else if (msc.metricsRanksStatement() != null) {
+ ranks = numberListOf(msc.metricsRanksStatement().numberList());
+ } else if (msc.metricsTimestampStatement() != null) {
+ timestamp = visitValueAccess(msc.metricsTimestampStatement().valueAccess());
+ }
+ }
+
+ return new MetricsBlock(name, scope, function, value, match, status, labels, buckets, ranks, timestamp);
+ }
+
+ private static List<String> numberListOf(final TALParser.NumberListContext ctx) {
+ final List<String> out = new ArrayList<>(ctx.NUMBER().size());
+ for (final TerminalNode n : ctx.NUMBER()) {
+ out.add(n.getText());
+ }
+ return out;
+ }
+
+ // ==================== Sink and persist ====================
+
+ private static SinkBlock visitSinkBlock(final TALParser.SinkBlockContext ctx) {
+ final List<VoteStatement> stmts = new ArrayList<>();
+ for (final TALParser.SinkStatementContext ssc : ctx.sinkContent().sinkStatement()) {
+ stmts.add(visitVoteStatement(
+ ssc.samplerBlock(), ssc.enforcerStatement(), ssc.dropperStatement(),
+ ssc.abortBlock(), ssc.ifStatement()));
+ }
+ return new SinkBlock(stmts);
+ }
+
+ private static PersistBlock visitPersistBlock(final TALParser.PersistBlockContext ctx) {
+ final List<VoteStatement> stmts = new ArrayList<>();
+ for (final TALParser.PersistStatementContext psc : ctx.persistContent().persistStatement()) {
+ stmts.add(visitVoteStatement(
+ psc.samplerBlock(), psc.enforcerStatement(), psc.dropperStatement(),
+ psc.abortBlock(), psc.ifStatement()));
+ }
+ return new PersistBlock(stmts);
+ }
+
+ /**
+ * {@code sink} and {@code persist} take the same statements, so one visitor serves both; the caller has
+ * already pulled the alternatives off its own context type.
+ */
+ private static VoteStatement visitVoteStatement(final TALParser.SamplerBlockContext sampler,
+ final TALParser.EnforcerStatementContext enforcer,
+ final TALParser.DropperStatementContext dropper,
+ final TALParser.AbortBlockContext abort,
+ final TALParser.IfStatementContext ifStatement) {
+ if (sampler != null) {
+ return visitSamplerBlock(sampler);
+ }
+ if (enforcer != null) {
+ return new EnforcerStatement();
+ }
+ if (dropper != null) {
+ return new DropperStatement();
+ }
+ if (abort != null) {
+ return new AbortStatement();
+ }
+ return visitIfStatement(ifStatement);
+ }
+
+ private static SamplerBlock visitSamplerBlock(final TALParser.SamplerBlockContext ctx) {
+ final List<SamplerContent> contents = new ArrayList<>();
+ for (final TALParser.RateLimitBlockContext rlc : ctx.samplerContent().rateLimitBlock()) {
+ contents.add(visitRateLimitBlock(rlc));
+ }
+ for (final TALParser.IfStatementContext isc : ctx.samplerContent().ifStatement()) {
+ contents.add(visitIfStatement(isc));
+ }
+ return new SamplerBlock(contents);
+ }
+
+ private static RateLimitBlock visitRateLimitBlock(final TALParser.RateLimitBlockContext rlc) {
+ final String id = stripQuotes(rlc.rateLimitId().getText());
+ final int rpm = parseStrictInt(rlc.rateLimitContent().NUMBER().getText(), "rpm");
+ return new RateLimitBlock(id, parseInterpolation(id), rpm);
+ }
+
+ // ==================== If statement ====================
+
+ private static IfBlock visitIfStatement(final TALParser.IfStatementContext ctx) {
+ final int condCount = ctx.condition().size();
+ final int bodyCount = ctx.ifBody().size();
+ final boolean hasElse = bodyCount > condCount;
+
+ // An else-if chain is built from the innermost branch backwards, so
+ // if (A) {b0} else if (B) {b1} else {b2}
+ // becomes IfBlock(A, b0, [IfBlock(B, b1, b2)]).
+ final List<FilterStatement> trailingElse = hasElse ? visitIfBody(ctx.ifBody(bodyCount - 1)) : null;
+
+ IfBlock nested = null;
+ for (int i = condCount - 1; i >= 1; i--) {
+ final List<FilterStatement> elsePart = nested != null ? List.of(nested) : trailingElse;
+ nested = new IfBlock(visitCondition(ctx.condition(i)), visitIfBody(ctx.ifBody(i)), elsePart);
+ }
+
+ final List<FilterStatement> topElse = nested != null ? List.of(nested) : trailingElse;
+ return new IfBlock(visitCondition(ctx.condition(0)), visitIfBody(ctx.ifBody(0)), topElse);
+ }
+
+ private static List<FilterStatement> visitIfBody(final TALParser.IfBodyContext ctx) {
+ final List<FilterStatement> stmts = new ArrayList<>();
+ for (final TALParser.FilterStatementContext fsc : ctx.filterStatement()) {
+ stmts.add(visitFilterStatement(fsc));
+ }
+ for (final TALParser.ExtractorStatementContext esc : ctx.extractorStatement()) {
+ stmts.add((FilterStatement) visitExtractorStatement(esc));
+ }
+ for (final TALParser.SinkStatementContext ssc : ctx.sinkStatement()) {
+ stmts.add((FilterStatement) visitVoteStatement(
+ ssc.samplerBlock(), ssc.enforcerStatement(), ssc.dropperStatement(),
+ ssc.abortBlock(), ssc.ifStatement()));
+ }
+ for (final TALParser.PersistStatementContext psc : ctx.persistStatement()) {
+ stmts.add((FilterStatement) visitVoteStatement(
+ psc.samplerBlock(), psc.enforcerStatement(), psc.dropperStatement(),
+ psc.abortBlock(), psc.ifStatement()));
+ }
+ final TALParser.SamplerContentContext sc = ctx.samplerContent();
+ if (sc != null) {
+ final List<SamplerContent> samplerItems = new ArrayList<>();
+ for (final TALParser.RateLimitBlockContext rlc : sc.rateLimitBlock()) {
+ samplerItems.add(visitRateLimitBlock(rlc));
+ }
+ for (final TALParser.IfStatementContext isc : sc.ifStatement()) {
+ samplerItems.add(visitIfStatement(isc));
+ }
+ if (!samplerItems.isEmpty()) {
+ stmts.add(new SamplerBlock(samplerItems));
+ }
+ }
+ return stmts;
+ }
+
+ // ==================== Conditions ====================
+
+ private static Condition visitCondition(final TALParser.ConditionContext ctx) {
+ if (ctx instanceof TALParser.CondAndContext) {
+ final TALParser.CondAndContext and = (TALParser.CondAndContext) ctx;
+ return new TALScriptModel.LogicalCondition(
+ visitCondition(and.condition(0)), LogicalOp.AND, visitCondition(and.condition(1)));
+ }
+ if (ctx instanceof TALParser.CondOrContext) {
+ final TALParser.CondOrContext or = (TALParser.CondOrContext) ctx;
+ return new TALScriptModel.LogicalCondition(
+ visitCondition(or.condition(0)), LogicalOp.OR, visitCondition(or.condition(1)));
+ }
+ if (ctx instanceof TALParser.CondNotContext) {
+ return new TALScriptModel.NotCondition(
+ visitCondition(((TALParser.CondNotContext) ctx).condition()));
+ }
+ if (ctx instanceof TALParser.CondEqContext) {
+ final TALParser.CondEqContext eq = (TALParser.CondEqContext) ctx;
+ return visitComparison(eq.conditionExpr(0), CompareOp.EQ, eq.conditionExpr(1));
+ }
+ if (ctx instanceof TALParser.CondNeqContext) {
+ final TALParser.CondNeqContext neq = (TALParser.CondNeqContext) ctx;
+ return visitComparison(neq.conditionExpr(0), CompareOp.NEQ, neq.conditionExpr(1));
+ }
+ if (ctx instanceof TALParser.CondGtContext) {
+ final TALParser.CondGtContext gt = (TALParser.CondGtContext) ctx;
+ return visitComparison(gt.conditionExpr(0), CompareOp.GT, gt.conditionExpr(1));
+ }
+ if (ctx instanceof TALParser.CondLtContext) {
+ final TALParser.CondLtContext lt = (TALParser.CondLtContext) ctx;
+ return visitComparison(lt.conditionExpr(0), CompareOp.LT, lt.conditionExpr(1));
+ }
+ if (ctx instanceof TALParser.CondGteContext) {
+ final TALParser.CondGteContext gte = (TALParser.CondGteContext) ctx;
+ return visitComparison(gte.conditionExpr(0), CompareOp.GTE, gte.conditionExpr(1));
+ }
+ if (ctx instanceof TALParser.CondLteContext) {
+ final TALParser.CondLteContext lte = (TALParser.CondLteContext) ctx;
+ return visitComparison(lte.conditionExpr(0), CompareOp.LTE, lte.conditionExpr(1));
+ }
+ return visitConditionExprAsCondition(((TALParser.CondSingleContext) ctx).conditionExpr());
+ }
+
+ private static Condition visitComparison(final TALParser.ConditionExprContext leftCtx,
+ final CompareOp op,
+ final TALParser.ConditionExprContext rightCtx) {
+ if (leftCtx instanceof TALParser.CondValueAccessContext) {
+ final TALParser.CondValueAccessContext lva = (TALParser.CondValueAccessContext) leftCtx;
+ return new TALScriptModel.ComparisonCondition(
+ visitValueAccess(lva.valueAccess()), extractCastType(lva.typeCast()), op,
+ visitConditionExprAsValue(rightCtx));
+ }
+ if (leftCtx instanceof TALParser.CondFunctionCallContext) {
+ final TALParser.FunctionInvocationContext fi =
+ ((TALParser.CondFunctionCallContext) leftCtx).functionInvocation();
+ return new TALScriptModel.ComparisonCondition(
+ functionCallAccess(fi), null, op, visitConditionExprAsValue(rightCtx));
+ }
+ return new TALScriptModel.ExprCondition(textAccess(leftCtx.getText()), null);
+ }
+
+ private static TALScriptModel.ConditionValue visitConditionExprAsValue(
+ final TALParser.ConditionExprContext ctx) {
+ if (ctx instanceof TALParser.CondStringContext) {
+ return new TALScriptModel.StringConditionValue(
+ stripQuotes(((TALParser.CondStringContext) ctx).STRING().getText()));
+ }
+ if (ctx instanceof TALParser.CondNumberContext) {
+ final String numText = ((TALParser.CondNumberContext) ctx).NUMBER().getText();
+ return new TALScriptModel.NumberConditionValue(parseLiteralAsDouble(numText), numText);
+ }
+ if (ctx instanceof TALParser.CondNullContext) {
+ return new TALScriptModel.NullConditionValue();
+ }
+ if (ctx instanceof TALParser.CondValueAccessContext) {
+ final TALParser.CondValueAccessContext va = (TALParser.CondValueAccessContext) ctx;
+ // valueAccessPrimary also matches NUMBER and NULL, and condValueAccess has priority over the
+ // dedicated alternatives, so a standalone literal arrives here and has to be recovered as one.
+ final TALParser.ValueAccessContext vaCtx = va.valueAccess();
+ final TALParser.ValueAccessTermContext singleTerm = singleTermOf(vaCtx);
+ if (va.typeCast() == null && singleTerm != null && singleTerm.valueAccessSegment().isEmpty()) {
+ final TALParser.ValueAccessPrimaryContext primary = singleTerm.valueAccessPrimary();
+ if (primary instanceof TALParser.ValueNumberContext) {
+ final String numText = ((TALParser.ValueNumberContext) primary).NUMBER().getText();
+ return new TALScriptModel.NumberConditionValue(parseLiteralAsDouble(numText), numText);
+ }
+ if (primary instanceof TALParser.ValueNullContext) {
+ return new TALScriptModel.NullConditionValue();
+ }
+ }
+ return new TALScriptModel.ValueAccessConditionValue(
+ visitValueAccess(vaCtx), extractCastType(va.typeCast()));
+ }
+ if (ctx instanceof TALParser.CondParenGroupContext) {
+ return new TALScriptModel.ValueAccessConditionValue(textAccess(ctx.getText()), null);
+ }
+ return new TALScriptModel.StringConditionValue(ctx.getText());
+ }
+
+ private static Condition visitConditionExprAsCondition(final TALParser.ConditionExprContext ctx) {
+ if (ctx instanceof TALParser.CondValueAccessContext) {
+ final TALParser.CondValueAccessContext va = (TALParser.CondValueAccessContext) ctx;
+ return new TALScriptModel.ExprCondition(
+ visitValueAccess(va.valueAccess()), extractCastType(va.typeCast()));
+ }
+ if (ctx instanceof TALParser.CondFunctionCallContext) {
+ return new TALScriptModel.ExprCondition(
+ functionCallAccess(((TALParser.CondFunctionCallContext) ctx).functionInvocation()), null);
+ }
+ if (ctx instanceof TALParser.CondParenGroupContext) {
+ return visitCondition(((TALParser.CondParenGroupContext) ctx).condition());
+ }
+ return new TALScriptModel.ExprCondition(textAccess(ctx.getText()), null);
+ }
+
+ // ==================== Value access ====================
+
+ private static ValueAccess visitValueAccess(final TALParser.ValueAccessContext ctx) {
+ return visitValueAccessAdd(ctx.valueAccessAdd());
+ }
+
+ private static ValueAccess visitValueAccessAdd(final TALParser.ValueAccessAddContext ctx) {
+ final List<TALParser.ValueAccessMulContext> muls = ctx.valueAccessMul();
+ if (muls.size() == 1) {
+ return visitValueAccessMul(muls.get(0));
+ }
+ final List<ValueAccess> parts = new ArrayList<>(muls.size());
+ for (final TALParser.ValueAccessMulContext mul : muls) {
+ parts.add(visitValueAccessMul(mul));
+ }
+ return binaryExpr(parts, collectInfixOps(ctx,
+ TALLexer.PLUS, BinaryOp.PLUS, TALLexer.MINUS, BinaryOp.MINUS));
+ }
+
+ private static ValueAccess visitValueAccessMul(final TALParser.ValueAccessMulContext ctx) {
+ final List<TALParser.ValueAccessTermContext> terms = ctx.valueAccessTerm();
+ if (terms.size() == 1) {
+ return visitValueAccessTerm(terms.get(0));
+ }
+ final List<ValueAccess> parts = new ArrayList<>(terms.size());
+ for (final TALParser.ValueAccessTermContext term : terms) {
+ parts.add(visitValueAccessTerm(term));
+ }
+ return binaryExpr(parts, collectInfixOps(ctx,
+ TALLexer.STAR, BinaryOp.STAR, TALLexer.SLASH, BinaryOp.SLASH));
+ }
+
+ /**
+ * Walk a context's terminal children to recover the infix operator sequence, one per gap between operands,
+ * which ANTLR's flattened child list does not give directly.
+ */
+ private static List<BinaryOp> collectInfixOps(final ParserRuleContext ctx,
+ final int firstToken, final BinaryOp firstOp,
+ final int secondToken, final BinaryOp secondOp) {
+ final List<BinaryOp> ops = new ArrayList<>();
+ for (int i = 0; i < ctx.getChildCount(); i++) {
+ final ParseTree child = ctx.getChild(i);
+ if (!(child instanceof TerminalNode)) {
+ continue;
+ }
+ final int type = ((TerminalNode) child).getSymbol().getType();
+ if (type == firstToken) {
+ ops.add(firstOp);
+ } else if (type == secondToken) {
+ ops.add(secondOp);
+ }
+ }
+ return ops;
+ }
+
+ private static ValueAccess binaryExpr(final List<ValueAccess> parts, final List<BinaryOp> ops) {
+ return new ValueAccess(List.of("expr"), false, false, false, false,
+ List.of(), null, null, parts, ops, null, null);
+ }
+
+ private static ValueAccess visitValueAccessTerm(final TALParser.ValueAccessTermContext ctx) {
+ final List<String> segments = new ArrayList<>();
+ boolean spanRef = false;
+ boolean metaRef = false;
+ boolean stringLiteral = false;
+ boolean numberLiteral = false;
+ String functionCallName = null;
+ List<TALScriptModel.FunctionArg> functionCallArgs = null;
+ ValueAccess parenInner = null;
+ String parenCast = null;
+
+ final TALParser.ValueAccessPrimaryContext primary = ctx.valueAccessPrimary();
+ if (primary instanceof TALParser.ValueSpanContext) {
+ spanRef = true;
+ segments.add("span");
+ } else if (primary instanceof TALParser.ValueMetaContext) {
+ metaRef = true;
+ segments.add("meta");
+ } else if (primary instanceof TALParser.ValueIdentifierContext) {
+ segments.add(((TALParser.ValueIdentifierContext) primary).IDENTIFIER().getText());
+ } else if (primary instanceof TALParser.ValueStringContext) {
+ stringLiteral = true;
+ segments.add(stripQuotes(((TALParser.ValueStringContext) primary).STRING().getText()));
+ } else if (primary instanceof TALParser.ValueNumberContext) {
+ numberLiteral = true;
+ segments.add(((TALParser.ValueNumberContext) primary).NUMBER().getText());
+ } else if (primary instanceof TALParser.ValueFunctionCallContext) {
+ final TALParser.FunctionInvocationContext fi =
+ ((TALParser.ValueFunctionCallContext) primary).functionInvocation();
+ functionCallName = fi.functionName().getText();
+ functionCallArgs = visitFunctionArgs(fi);
+ segments.add(fi.getText());
+ } else if (primary instanceof TALParser.ValueParenContext) {
+ final TALParser.ValueParenContext parenCtx = (TALParser.ValueParenContext) primary;
+ parenInner = visitValueAccess(parenCtx.valueAccess());
+ parenCast = extractCastType(parenCtx.typeCast());
+ segments.add("paren");
+ } else {
+ segments.add(primary.getText());
+ }
+
+ final List<ValueAccessSegment> chain = new ArrayList<>();
+ for (final TALParser.ValueAccessSegmentContext seg : ctx.valueAccessSegment()) {
+ if (seg instanceof TALParser.SegmentFieldContext) {
+ final String name = ((TALParser.SegmentFieldContext) seg).anyIdentifier().getText();
+ segments.add(name);
+ chain.add(new FieldSegment(name, false));
+ } else if (seg instanceof TALParser.SegmentSafeFieldContext) {
+ final String name = ((TALParser.SegmentSafeFieldContext) seg).anyIdentifier().getText();
+ segments.add(name);
+ chain.add(new FieldSegment(name, true));
+ } else if (seg instanceof TALParser.SegmentMethodContext) {
+ final TALParser.FunctionInvocationContext fi =
+ ((TALParser.SegmentMethodContext) seg).functionInvocation();
+ segments.add(fi.functionName().getText() + "()");
+ chain.add(new TALScriptModel.MethodSegment(
+ fi.functionName().getText(), visitFunctionArgs(fi), false));
+ } else if (seg instanceof TALParser.SegmentSafeMethodContext) {
+ final TALParser.FunctionInvocationContext fi =
+ ((TALParser.SegmentSafeMethodContext) seg).functionInvocation();
+ segments.add(fi.functionName().getText() + "()");
+ chain.add(new TALScriptModel.MethodSegment(
+ fi.functionName().getText(), visitFunctionArgs(fi), true));
+ } else if (seg instanceof TALParser.SegmentIndexContext) {
+ final int index = parseStrictInt(
+ ((TALParser.SegmentIndexContext) seg).NUMBER().getText(), "[index]");
+ segments.add("[" + index + "]");
+ chain.add(new IndexSegment(index));
+ }
+ }
+
+ return new ValueAccess(segments, spanRef, metaRef, stringLiteral, numberLiteral,
+ chain, functionCallName, functionCallArgs, List.of(), List.of(), parenInner, parenCast);
+ }
+
+ private static List<TALScriptModel.FunctionArg> visitFunctionArgs(
+ final TALParser.FunctionInvocationContext fi) {
+ if (fi.functionArgList() == null) {
+ return List.of();
+ }
+ final List<TALScriptModel.FunctionArg> args = new ArrayList<>();
+ for (final TALParser.FunctionArgContext fac : fi.functionArgList().functionArg()) {
+ if (fac.detectPoint() != null) {
+ // CLIENT / SERVER are written bare as a relation constructor's first argument; they reach the
+ // generator as a plain identifier, which only the entity constructors accept.
+ args.add(new TALScriptModel.FunctionArg(textAccess(fac.detectPoint().getText()), null));
+ } else if (fac.valueAccess() != null) {
+ args.add(new TALScriptModel.FunctionArg(
+ visitValueAccess(fac.valueAccess()), extractCastType(fac.typeCast())));
+ } else if (fac.STRING() != null) {
+ args.add(new TALScriptModel.FunctionArg(
+ literalArg(stripQuotes(fac.STRING().getText()), true, false), null));
+ } else if (fac.NUMBER() != null) {
+ args.add(new TALScriptModel.FunctionArg(
+ literalArg(fac.NUMBER().getText(), false, true), null));
+ } else if (fac.boolValue() != null) {
+ args.add(new TALScriptModel.FunctionArg(
+ literalArg(fac.boolValue().getText(), false, false), null));
+ } else {
+ args.add(new TALScriptModel.FunctionArg(textAccess("null"), null));
+ }
+ }
+ return args;
+ }
+
+ private static ValueAccess functionCallAccess(final TALParser.FunctionInvocationContext fi) {
+ return new ValueAccess(List.of(fi.getText()), false, false, false, false,
+ List.of(), fi.functionName().getText(), visitFunctionArgs(fi));
+ }
+
+ /**
+ * A single-segment, no-chain access carrying raw text, for the forms the model has no richer shape for.
+ */
+ private static ValueAccess textAccess(final String text) {
+ return new ValueAccess(List.of(text), false, false, List.of());
+ }
+
+ private static ValueAccess literalArg(final String text,
+ final boolean stringLiteral,
+ final boolean numberLiteral) {
+ return new ValueAccess(List.of(text), false, false, stringLiteral, numberLiteral,
+ List.of(), null, null);
+ }
+
+ private static String resolveValueAsString(final TALParser.ValueAccessContext ctx) {
+ final TALParser.ValueAccessTermContext term = singleTermOf(ctx);
+ if (term == null) {
+ return ctx.getText();
+ }
+ final TALParser.ValueAccessPrimaryContext primary = term.valueAccessPrimary();
+ if (primary instanceof TALParser.ValueStringContext) {
+ return stripQuotes(((TALParser.ValueStringContext) primary).STRING().getText());
+ }
+ return primary.getText();
+ }
+
+ /**
+ * @return the single term of a {@code valueAccess} that carries no arithmetic operators, else null
+ */
+ private static TALParser.ValueAccessTermContext singleTermOf(final TALParser.ValueAccessContext ctx) {
+ final TALParser.ValueAccessAddContext add = ctx.valueAccessAdd();
+ if (add.valueAccessMul().size() != 1) {
+ return null;
+ }
+ final TALParser.ValueAccessMulContext mul = add.valueAccessMul(0);
+ if (mul.valueAccessTerm().size() != 1) {
+ return null;
+ }
+ return mul.valueAccessTerm(0);
+ }
+
+ // ==================== Utilities ====================
+
+ /**
+ * Parse a NUMBER literal that must be a plain integer. The lexer's NUMBER token also carries the decimal,
+ * exponent and suffix forms arithmetic accepts, which the {@code rpm} and {@code [index]} slots cannot.
+ */
+ private static long parseStrictInteger(final String numText, final String slot) {
+ for (int i = 0; i < numText.length(); i++) {
+ final char c = numText.charAt(i);
+ if (c < '0' || c > '9') {
+ throw new IllegalArgumentException(
+ slot + " expects a plain integer literal, got '" + numText
+ + "' (suffixes / decimals / exponents are not accepted here)");
+ }
+ }
+ try {
+ return Long.parseLong(numText);
+ } catch (NumberFormatException e) {
+ throw new IllegalArgumentException(
+ slot + " value '" + numText + "' exceeds the supported range (must fit in a Java long)");
+ }
+ }
+
+ private static int parseStrictInt(final String numText, final String slot) {
+ final long value = parseStrictInteger(numText, slot);
+ if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) {
+ throw new IllegalArgumentException(
+ slot + " value '" + numText + "' exceeds the supported range (must fit in a Java int)");
+ }
+ return (int) value;
+ }
+
+ private static double parseLiteralAsDouble(final String numText) {
+ String t = numText;
+ if (!t.isEmpty()) {
+ final char last = t.charAt(t.length() - 1);
+ if (last == 'L' || last == 'l' || last == 'F' || last == 'f' || last == 'D' || last == 'd') {
+ t = t.substring(0, t.length() - 1);
+ }
+ }
+ return Double.parseDouble(t);
+ }
+
+ /**
+ * Resolve a {@code typeCast} context to its cast name. Accepts a null context so call sites can pass
+ * {@code ctx.typeCast()} without a guard.
+ */
+ private static String extractCastType(final TALParser.TypeCastContext ctx) {
+ if (ctx == null) {
+ return null;
+ }
+ if (ctx.STRING_TYPE() != null) {
+ return "String";
+ }
+ if (ctx.LONG_TYPE() != null) {
+ return "Long";
+ }
+ if (ctx.INTEGER_TYPE() != null) {
+ return "Integer";
+ }
+ if (ctx.DOUBLE_TYPE() != null) {
+ return "Double";
+ }
+ if (ctx.FLOAT_TYPE() != null) {
+ return "Float";
+ }
+ if (ctx.BOOLEAN_TYPE() != null) {
+ return "Boolean";
+ }
+ if (ctx.qualifiedName() != null) {
+ return ctx.qualifiedName().getText();
+ }
+ return null;
+ }
+
+ static String stripQuotes(final String s) {
+ if (s == null || s.length() < 2) {
+ return s;
+ }
+ final char first = s.charAt(0);
+ if ((first == '\'' || first == '"') && s.charAt(s.length() - 1) == first) {
+ return s.substring(1, s.length() - 1);
+ }
+ return s;
+ }
+
+ private static String truncate(final String s, final int maxLen) {
+ return s.length() <= maxLen ? s : s.substring(0, maxLen) + "...";
+ }
+
+ // ==================== Interpolation ====================
+
+ /**
+ * Parse {@code ${...}} placeholders in a rate-limit id, so one rule can keep a counter per service or per
+ * endpoint. {@code "slow-sql-${meta.service}"} yields [literal("slow-sql-"), expr(meta.service)].
+ *
+ * @param s the id as written
+ * @return the parts, or null when the id carries no placeholder
+ */
+ static List<InterpolationPart> parseInterpolation(final String s) {
+ if (!s.contains("${")) {
+ return null;
+ }
+ final List<InterpolationPart> parts = new ArrayList<>();
+ int pos = 0;
+ while (pos < s.length()) {
+ final int start = s.indexOf("${", pos);
+ if (start < 0) {
+ if (pos < s.length()) {
+ parts.add(InterpolationPart.ofLiteral(s.substring(pos)));
+ }
+ break;
+ }
+ if (start > pos) {
+ parts.add(InterpolationPart.ofLiteral(s.substring(pos, start)));
+ }
+ int depth = 1;
+ int i = start + 2;
+ while (i < s.length() && depth > 0) {
+ final char c = s.charAt(i);
+ if (c == '{') {
+ depth++;
+ } else if (c == '}') {
+ depth--;
+ }
+ i++;
+ }
+ if (depth != 0) {
+ throw new IllegalArgumentException("Unclosed interpolation in: " + s);
+ }
+ parts.add(InterpolationPart.ofExpression(parseValueAccessExpr(s.substring(start + 2, i - 1))));
+ pos = i;
+ }
+ return parts;
+ }
+
+ /**
+ * Parse a standalone expression by wrapping it in a minimal rule, since the grammar's entry point is a whole
+ * {@code filter} block.
+ */
+ private static ValueAccess parseValueAccessExpr(final String expr) {
+ final TALScriptModel model = parse("filter { if (" + expr + ") { abort {} } }");
+ final Condition cond = ((IfBlock) model.getStatements().get(0)).getCondition();
+ if (cond instanceof TALScriptModel.ExprCondition) {
+ return ((TALScriptModel.ExprCondition) cond).getExpr();
+ }
+ if (cond instanceof TALScriptModel.ComparisonCondition) {
+ return ((TALScriptModel.ComparisonCondition) cond).getLeft();
+ }
+ throw new IllegalArgumentException("Cannot parse interpolation expression: " + expr);
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALSpanRootResolver.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALSpanRootResolver.java
new file mode 100644
index 0000000000..731d64d560
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALSpanRootResolver.java
@@ -0,0 +1,234 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.apache.skywalking.oap.server.core.dsl.DslJavaSourceText;
+import org.apache.skywalking.oap.server.core.trace.SpanMetadata;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFieldSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionArg;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALIndexSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALMethodSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessSegment;
+
+/**
+ * What TAL contributes to {@link TALValueCodegen}: the {@code span} and {@code meta} roots, the attribute
+ * functions the semantic conventions are read through, and the two lookups a peer's name goes through,
+ * {@code component} and {@code resolveAlias}.
+ *
+ * <p>The entity constructors are function calls too, but they are not resolved here: only a {@code def} or a
+ * {@code scope} may hold one, so {@link TALBlockCodegen} recognizes them by name where they are legal, and
+ * anywhere else they fall through to the "no matching codegen path" error.
+ */
+public class TALSpanRootResolver implements TALRootResolver {
+ /**
+ * The attribute functions, each taking one or more keys and returning a string.
+ */
+ private static final List<String> STRING_FUNCTIONS = List.of("attr", "resource", "scopeAttr");
+
+ /**
+ * The entity constructors, which only {@link TALBlockCodegen} may emit.
+ */
+ static final List<String> ENTITY_CONSTRUCTORS =
+ List.of("service", "instance", "endpoint", "serviceRelation", "serviceInstanceRelation");
+
+ /**
+ * The rule's declared input type name, kept for diagnostics.
+ */
+ private final String inputTypeName;
+
+ public TALSpanRootResolver(final Class<?> inputType) {
+ this.inputTypeName = inputType == null ? "<none>" : inputType.getName();
+ }
+
+ @Override
+ public boolean generateFunctionCall(final StringBuilder sb, final TALValueAccess value,
+ final TALGenCtx genCtx) {
+ final String name = value.getFunctionCallName();
+ if (STRING_FUNCTIONS.contains(name)) {
+ appendKeyedCall(sb, "h." + name, value, 1);
+ return true;
+ }
+ if ("hasAttr".equals(name)) {
+ appendKeyedCall(sb, "h.hasAttr", value, 1);
+ return true;
+ }
+ if ("event".equals(name)) {
+ requireKeys(value, name, 1, 1);
+ sb.append("h.event(\"").append(literalArg(value, 0)).append("\")");
+ return true;
+ }
+ if ("eventAttr".equals(name)) {
+ requireKeys(value, name, 2, Integer.MAX_VALUE);
+ sb.append("h.eventAttr(");
+ for (int i = 0; i < value.getFunctionCallArgs().size(); i++) {
+ if (i > 0) {
+ sb.append(", ");
+ }
+ sb.append("\"").append(literalArg(value, i)).append("\"");
+ }
+ sb.append(")");
+ return true;
+ }
+ if ("component".equals(name) || "resolveAlias".equals(name) || "urlHost".equals(name)) {
+ requireKeys(value, name, 1, 1);
+ sb.append("h.").append(name).append("(");
+ TALValueCodegen.generateStringValueAccess(
+ sb, value.getFunctionCallArgs().get(0).getValue(), null, genCtx);
+ sb.append(")");
+ return true;
+ }
+ return false;
+ }
+
+ /**
+ * {@code meta.*} walks {@link SpanMetadata}'s getters, so a chain that names a field the class does not have
+ * is a compile error rather than a null at runtime.
+ */
+ @Override
+ public void generateMetaRootAccess(final StringBuilder sb,
+ final List<? extends TALValueAccessSegment> chain,
+ final TALGenCtx genCtx) {
+ sb.append(chainAccess(chain, SpanMetadata.class, "h.ctx().getMeta()", false, genCtx, false));
+ }
+
+ /**
+ * {@code span.*} walks the rule's declared input type from the wire object.
+ */
+ @Override
+ public void generateInputRootAccess(final StringBuilder sb,
+ final List<? extends TALValueAccessSegment> chain,
+ final TALGenCtx genCtx) {
+ if (genCtx.inputType == null) {
+ throw new IllegalArgumentException(
+ "span.* is only resolvable when the rule declares a single inputType; " + describeContext());
+ }
+ sb.append(chainAccess(chain, genCtx.inputType, "_p", true, genCtx, true));
+ }
+
+ @Override
+ public ExprType functionReturnType(final String functionName) {
+ if (STRING_FUNCTIONS.contains(functionName)) {
+ return ExprType.STRING;
+ }
+ if ("hasAttr".equals(functionName)) {
+ return ExprType.BOOLEAN;
+ }
+ if ("eventAttr".equals(functionName) || "resolveAlias".equals(functionName)
+ || "urlHost".equals(functionName)) {
+ return ExprType.STRING;
+ }
+ if ("component".equals(functionName)) {
+ return ExprType.INT;
+ }
+ return null;
+ }
+
+ /**
+ * A span always arrives as a declared type, so a chain on the input root is always walkable by reflection.
+ */
+ @Override
+ public boolean isTypedInputActive() {
+ return true;
+ }
+
+ @Override
+ public String describeContext() {
+ return "inputType: " + inputTypeName;
+ }
+
+ /**
+ * Walk the leading field segments against a typed root, then apply whatever method and index segments follow,
+ * which is the shape every root chain takes. A root the rule can overwrite is read inline; see
+ * {@link TALValueCodegen#generateInlineChainAccess}.
+ */
+ private static String chainAccess(final List<? extends TALValueAccessSegment> chain,
+ final Class<?> rootType,
+ final String rootExpr,
+ final boolean rootCanBeNull,
+ final TALGenCtx genCtx,
+ final boolean cacheable) {
+ final List<TALFieldSegment> fieldSegments = new ArrayList<>();
+ int tailStart = -1;
+ for (int i = 0; i < chain.size(); i++) {
+ final TALValueAccessSegment seg = chain.get(i);
+ if (seg instanceof TALFieldSegment) {
+ fieldSegments.add((TALFieldSegment) seg);
+ } else {
+ tailStart = i;
+ break;
+ }
+ }
+
+ String current = cacheable
+ ? TALValueCodegen.generateTypedChainAccess(fieldSegments, rootType, rootExpr, rootCanBeNull, genCtx)
+ : TALValueCodegen.generateInlineChainAccess(fieldSegments, rootType, rootExpr, genCtx);
+
+ if (tailStart >= 0) {
+ for (int i = tailStart; i < chain.size(); i++) {
+ final TALValueAccessSegment seg = chain.get(i);
+ if (seg instanceof TALMethodSegment) {
+ current = TALValueCodegen.appendMethodSegment(current, (TALMethodSegment) seg, genCtx);
+ } else if (seg instanceof TALIndexSegment) {
+ current = current + "[" + ((TALIndexSegment) seg).getIndex() + "]";
+ } else if (seg instanceof TALFieldSegment) {
+ current = current + "." + ((TALFieldSegment) seg).getName();
+ }
+ }
+ }
+ return current;
+ }
+
+ /**
+ * Emit a call whose arguments are all string-literal keys, which every attribute function takes.
+ */
+ private static void appendKeyedCall(final StringBuilder sb, final String method,
+ final TALValueAccess value, final int minKeys) {
+ requireKeys(value, value.getFunctionCallName(), minKeys, Integer.MAX_VALUE);
+ sb.append(method).append("(");
+ for (int i = 0; i < value.getFunctionCallArgs().size(); i++) {
+ if (i > 0) {
+ sb.append(", ");
+ }
+ sb.append("\"").append(literalArg(value, i)).append("\"");
+ }
+ sb.append(")");
+ }
+
+ private static String literalArg(final TALValueAccess value, final int index) {
+ final TALFunctionArg arg = value.getFunctionCallArgs().get(index);
+ if (!arg.getValue().isStringLiteral()) {
+ throw new IllegalArgumentException(
+ value.getFunctionCallName() + "() takes string literal arguments; got "
+ + arg.getValue().toPathString());
+ }
+ return DslJavaSourceText.toLiteral(arg.getValue().getSegments().get(0));
+ }
+
+ private static void requireKeys(final TALValueAccess value, final String name,
+ final int min, final int max) {
+ final int count = value.getFunctionCallArgs().size();
+ if (count < min || count > max) {
+ throw new IllegalArgumentException(
+ name + "() expects " + (min == max ? String.valueOf(min) : "at least " + min)
+ + " argument(s), got " + count);
+ }
+ }
+}
diff --git a/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALValueCodegen.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALValueCodegen.java
new file mode 100644
index 0000000000..98fabfad80
--- /dev/null
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/TALValueCodegen.java
@@ -0,0 +1,1543 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler;
+
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.BinaryOp;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALBoolConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALComparisonCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALExprCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFieldSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALFunctionArg;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALIndexSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALLogicalCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALMethodSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNotCondition;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNullConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALNumberConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALStringConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccess;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessConditionValue;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.TALValueAccessSegment;
+import org.apache.skywalking.oap.trace.analyzer.v2.compiler.model.LogicalOp;
+
+import java.util.List;
+import org.apache.skywalking.oap.server.core.dsl.DslJavaSourceText;
+import java.lang.reflect.Method;
+
+/**
+ * The expression half of every DSL's code generation: value access, conditions, casts, arithmetic and the
+ * reflective getter chains, emitted as Java source for Javassist to compile.
+ *
+ * <p>What a rule can start an expression with — {@code span}, {@code meta}, {@code attr()} — is supplied by
+ * {@link TALRootResolver}. Everything below is independent of spans:
+ *
+ * <pre>{@code
+ * Expression type Example Generated code
+ * ─────────────────────── ─────────────────────────────────── ────────────────────────────
+ * String literal "SLOW_SQL" "SLOW_SQL"
+ * Number literal 500 Integer.valueOf(500)
+ * Typed root chain span?.status?.message ((Type)_p).getStatus()...
+ * def variable myVar?.getAsString() _def_myVar?.getAsString()
+ * Parenthesized (expr as String).trim() h.toStr(...).trim()
+ * String concat "${meta.service}:${meta.endpoint}" "" + ... + ":" + ...
+ * Arithmetic (int) (a as Integer) + (b as Integer) Integer.valueOf(h.toInt(..) + h.toInt(..))
+ * Arithmetic (mixed) (a as Integer) * (b as Long) Long.valueOf((long) h.toInt(..) * h.toLong(..))
+ * }</pre>
+ *
+ * <p>Condition codegen ({@link #generateCondition}) handles comparisons ({@code ==}, {@code !=}, {@code <},
+ * {@code >}), logical operators, negation and expression-as-boolean.
+ *
+ * <p>Sibling implementation: {@code LALValueCodegen} in {@code log-analyzer} compiles the same expression grammar
+ * for LAL. The two are deliberately separate copies so that no change here can reach log parsing, which means a
+ * fix to a shared defect has to be applied in both. Check the sibling before concluding a bug is TAL-only.
+ */
+public final class TALValueCodegen {
+ private TALValueCodegen() {
+ // utility class
+ }
+
+ // ==================== Conditions ====================
+
+ /**
+ * Generates code for an {@code if} condition expression.
+ *
+ * <p>TAL examples and their generated code:
+ * <pre>{@code
+ * // Comparison (==, !=):
+ * if (tag("LOG_KIND") == "SLOW_SQL")
+ * → java.util.Objects.equals(h.tagValue("LOG_KIND"), "SLOW_SQL")
+ *
+ * // Numeric comparison (<, >, <=, >=):
+ * if (parsed?.response?.responseCode?.value as Integer < 400)
+ * → ((Type)_p).getResponse().getResponseCode().getValue() < 400L
+ *
+ * // Logical operators:
+ * if (condA && condB) → (condA && condB)
+ * if (!cond) → !(cond)
+ *
+ * // Expression-as-boolean (truthy check):
+ * if (parsed?.commonProperties?.responseFlags?.toString())
+ * → h.isNotEmpty(h.toString(...))
+ * }</pre>
+ */
+ public static void generateCondition(final StringBuilder sb,
+ final TALCondition cond,
+ final TALGenCtx genCtx) {
+ if (cond instanceof TALComparisonCondition) {
+ final TALComparisonCondition cc =
+ (TALComparisonCondition) cond;
+ switch (cc.getOp()) {
+ case EQ:
+ if (isNumericComparison(cc, genCtx)) {
+ generateNumericComparison(sb, cc, " == ", genCtx);
+ } else {
+ sb.append("java.util.Objects.equals(");
+ generateValueAccessObj(sb, cc.getLeft(), cc.getLeftCast(), genCtx);
+ sb.append(", ");
+ generateConditionValue(sb, cc.getRight(), genCtx);
+ sb.append(")");
+ }
+ break;
+ case NEQ:
+ if (isNumericComparison(cc, genCtx)) {
+ generateNumericComparison(sb, cc, " != ", genCtx);
+ } else {
+ sb.append("!java.util.Objects.equals(");
+ generateValueAccessObj(sb, cc.getLeft(), cc.getLeftCast(), genCtx);
+ sb.append(", ");
+ generateConditionValue(sb, cc.getRight(), genCtx);
+ sb.append(")");
+ }
+ break;
+ case GT:
+ generateNumericComparison(sb, cc, " > ", genCtx);
+ break;
+ case LT:
+ generateNumericComparison(sb, cc, " < ", genCtx);
+ break;
+ case GTE:
+ generateNumericComparison(sb, cc, " >= ", genCtx);
+ break;
+ case LTE:
+ generateNumericComparison(sb, cc, " <= ", genCtx);
+ break;
+ default:
+ break;
+ }
+ } else if (cond instanceof TALLogicalCondition) {
+ final TALLogicalCondition lc =
+ (TALLogicalCondition) cond;
+ sb.append("(");
+ generateCondition(sb, lc.getLeft(), genCtx);
+ sb.append(lc.getOp() == LogicalOp.AND
+ ? " && " : " || ");
+ generateCondition(sb, lc.getRight(), genCtx);
+ sb.append(")");
+ } else if (cond instanceof TALNotCondition) {
+ sb.append("!(");
+ generateCondition(sb,
+ ((TALNotCondition) cond).getInner(), genCtx);
+ sb.append(")");
+ } else if (cond instanceof TALExprCondition) {
+ final String ct = ((TALExprCondition) cond).getCastType();
+ final TALValueAccess expr = ((TALExprCondition) cond).getExpr();
+ // A built-in that already returns boolean is the condition. Wrapping it would hand a primitive to
+ // an Object overload, which Javassist compiles without autoboxing and the verifier then rejects.
+ if (ct == null && expr.getFunctionCallName() != null
+ && genCtx.resolver.functionReturnType(expr.getFunctionCallName()) == ExprType.BOOLEAN) {
+ generateValueAccess(sb, expr, genCtx);
+ return;
+ }
+ final String method = "Boolean".equals(ct) || "boolean".equals(ct)
+ ? ".isTrue(" : ".isNotEmpty(";
+ sb.append("h").append(method);
+ generateValueAccessObj(sb, expr, ct, genCtx);
+ sb.append(")");
+ }
+ }
+
+ public static void generateNumericComparison(
+ final StringBuilder sb,
+ final TALComparisonCondition cc,
+ final String op,
+ final TALGenCtx genCtx) {
+ // Decide the primitive comparison type from explicit casts and the
+ // operand shapes — both sides influence the choice via JLS-style
+ // promotion. RHS-side cast is read off ValueAccessConditionValue;
+ // RHS literals contribute via their inferred numeric type.
+ final ExprType lhsType = inferComparisonOperandType(cc.getLeft(), cc.getLeftCast(), genCtx);
+ final ExprType rhsType = inferRightHandType(cc.getRight(), genCtx);
+ final ExprType cmpType = pickComparisonType(lhsType, rhsType);
+ final Class<?> cmpClass = cmpType.primitiveClass;
+
+ // Render the LHS via the shared helper, then capture the null-guard
+ // before the RHS rendering overwrites it. A top-level numeric cast
+ // on the comparison (`tag("a") as Integer < 1.5`) is honoured by
+ // emitOperandRespectingCast so the operand is rendered in the
+ // user's declared primitive, not in the promoted comparison type.
+ genCtx.lastNullChecks = null;
+ final String leftExpr = renderAsPrimitive(
+ cc.getLeft(), cc.getLeftCast(), cmpType, genCtx);
+ final String lhsNullChecks = genCtx.lastNullChecks;
+
+ // Render the RHS into its own buffer so we can read back any null
+ // guards it produced (e.g. from a typed-proto chain like
+ // `parsed?.response?.responseCode?.value`) and apply them at the
+ // outer ternary alongside the LHS guards.
+ genCtx.lastNullChecks = null;
+ final StringBuilder rhsBuf = new StringBuilder();
+ generateConditionValueNumeric(rhsBuf, cc.getRight(), cmpClass, genCtx);
+ final String rhsNullChecks = genCtx.lastNullChecks;
+
+ final String combinedNullChecks = combineNullChecks(lhsNullChecks, rhsNullChecks);
+ if (combinedNullChecks != null) {
+ sb.append("(").append(combinedNullChecks).append(" ? false : ")
+ .append(leftExpr).append(op).append(rhsBuf).append(")");
+ } else {
+ sb.append(leftExpr).append(op).append(rhsBuf);
+ }
+ }
+
+ /**
+ * Combine LHS / RHS null-guard expressions for a comparison. Either side
+ * may be {@code null} (no guard); the result is the disjunction so the
+ * comparison short-circuits to {@code false} as soon as any participant
+ * is null, mirroring the previous single-side behaviour.
+ */
+ private static String combineNullChecks(final String lhs, final String rhs) {
+ if (lhs == null && rhs == null) {
+ return null;
+ }
+ if (lhs == null) {
+ return rhs;
+ }
+ if (rhs == null) {
+ return lhs;
+ }
+ return lhs + " || " + rhs;
+ }
+
+ /**
+ * Decide whether an {@code ==} / {@code !=} comparison should be
+ * routed through numeric primitive comparison rather than
+ * {@code Objects.equals}. True when BOTH sides resolve to a numeric
+ * type (via explicit cast, paren-cast, or AST inference). A numeric
+ * literal RHS is enough on its own — Java promotes the LHS to match.
+ */
+ private static boolean isNumericComparison(
+ final TALComparisonCondition cc,
+ final TALGenCtx genCtx) {
+ if (cc.getRight() instanceof TALNumberConditionValue) {
+ return true;
+ }
+ if (!(cc.getRight() instanceof TALValueAccessConditionValue)) {
+ return false;
+ }
+ final TALValueAccessConditionValue vacv =
+ (TALValueAccessConditionValue) cc.getRight();
+ return numericTypeOrNull(cc.getLeft(), cc.getLeftCast(), genCtx) != null
+ && numericTypeOrNull(vacv.getValue(), vacv.getCastType(), genCtx) != null;
+ }
+
+ /**
+ * Return the operand's numeric {@link ExprType} if and only if it
+ * resolves to one of {@code INT / LONG / FLOAT / DOUBLE} via an
+ * explicit cast or compile-time inference; otherwise {@code null}.
+ * Used by {@link #isNumericComparison} to decide whether {@code ==} /
+ * {@code !=} should compare primitives — note this is strict (no
+ * {@code LONG} fallback like {@link #inferComparisonOperandType}).
+ */
+ private static ExprType numericTypeOrNull(
+ final TALValueAccess value,
+ final String topLevelCast,
+ final TALGenCtx genCtx) {
+ final ExprType fromCast = castToType(topLevelCast);
+ if (fromCast.isNumeric()) {
+ return fromCast;
+ }
+ final ExprType inferred = inferType(value, genCtx);
+ return inferred.isNumeric() ? inferred : null;
+ }
+
+ /**
+ * Read the numeric type the user declared for the left side of a
+ * comparison. Same shape as {@link #numericTypeOrNull} but with a
+ * {@code LONG} fallback for non-numeric inputs — used when the
+ * comparison itself must still pick a primitive home (e.g. an
+ * unbound {@code parsed.x} on the LHS still goes through
+ * {@code h.toLong}).
+ */
+ private static ExprType inferComparisonOperandType(
+ final TALValueAccess value,
+ final String topLevelCast,
+ final TALGenCtx genCtx) {
+ final ExprType numeric = numericTypeOrNull(value, topLevelCast, genCtx);
+ return numeric != null ? numeric : ExprType.LONG;
+ }
+
+ /**
+ * Read the numeric type of a comparison's RHS — literal type for
+ * number literals; declared cast (or inferred type) for value accesses;
+ * otherwise {@link ExprType#UNKNOWN}.
+ */
+ private static ExprType inferRightHandType(
+ final TALConditionValue cv,
+ final TALGenCtx genCtx) {
+ if (cv instanceof TALNumberConditionValue) {
+ final String literal = ((TALNumberConditionValue) cv).getLiteral();
+ return literal != null ? NumericLiteral.parse(literal).type : ExprType.LONG;
+ }
+ if (cv instanceof TALValueAccessConditionValue) {
+ final TALValueAccessConditionValue vacv =
+ (TALValueAccessConditionValue) cv;
+ final ExprType numeric = numericTypeOrNull(vacv.getValue(), vacv.getCastType(), genCtx);
+ if (numeric != null) {
+ return numeric;
+ }
+ return inferType(vacv.getValue(), genCtx);
+ }
+ return ExprType.UNKNOWN;
+ }
+
+ /**
+ * Pick the JLS-promoted primitive type for a comparison given both sides'
+ * inferred types. Numeric sides drive promotion; non-numeric sides default
+ * to {@code LONG} so the comparison still has a primitive home.
+ */
+ private static ExprType pickComparisonType(final ExprType lhs, final ExprType rhs) {
+ if (lhs.isNumeric() && rhs.isNumeric()) {
+ return promote(lhs, rhs);
+ }
+ if (lhs.isNumeric()) {
+ return lhs;
+ }
+ if (rhs.isNumeric()) {
+ return rhs;
+ }
+ return ExprType.LONG;
+ }
+
+ /**
+ * Emit a primitive widening cast on an already-primitive expression, only
+ * when the source type is narrower than the target.
+ */
+ private static String widenPrimitiveExpr(final String expr,
+ final ExprType from,
+ final ExprType to) {
+ if (from == to || promote(from, to) == from) {
+ return expr;
+ }
+ return "(" + to.primitiveKeyword + ") " + expr;
+ }
+
+ /**
+ * Render an operand for a numeric comparison while preserving the user's
+ * declared cast. Two-phase to avoid double-coercion:
+ * <ol>
+ * <li>Render the operand expression. Typed proto fields, arithmetic
+ * results, and paren-cast operands already land as a primitive and
+ * record the type via {@code genCtx.lastResolvedType}.</li>
+ * <li>If the rendered expression is non-primitive (a boxed/Object)
+ * and the user declared a numeric cast, wrap it with the matching
+ * {@code h.toX()} helper so the primitive identity is preserved
+ * — e.g. {@code tag("a") as Integer < 1.5} renders
+ * {@code (double) h.toInt(h.tagValue("a")) < 1.5}, not
+ * {@code h.toDouble(h.tagValue("a")) < 1.5}.</li>
+ * </ol>
+ */
+ private static void emitOperandRespectingCast(
+ final StringBuilder sb,
+ final TALValueAccess value,
+ final String castType,
+ final TALGenCtx genCtx) {
+ final int start = sb.length();
+ generateValueAccessObj(sb, value, castType, genCtx);
+ final Class<?> resolved = genCtx.lastResolvedType;
+ final boolean alreadyPrimitive = resolved != null && resolved.isPrimitive();
+ final ExprType castET = castToType(castType);
+ if (alreadyPrimitive) {
+ // Native primitive. If the user declared a different numeric
+ // type, honour it via a Java primitive cast — e.g.
+ // `((tag("a") as Long) + 1) as Integer` should narrow the long
+ // sum to int rather than silently keep the long value. Read
+ // the primitive form from lastRawChain (sb may hold a boxed
+ // wrapper like `Long.valueOf(...)` that the verifier can't
+ // unbox via a primitive cast). Preserve any null-guard the
+ // inner generator captured (typed-proto safe-nav) so the
+ // outer comparison can still short-circuit on a missing
+ // chain.
+ if (castET.isNumeric()
+ && exprTypeFromClass(resolved) != castET
+ && genCtx.lastRawChain != null) {
+ final String preservedNullChecks = genCtx.lastNullChecks;
+ final String primExpr = genCtx.lastRawChain;
+ sb.setLength(start);
+ sb.append("(").append(castET.primitiveKeyword)
+ .append(") (").append(primExpr).append(")");
+ recordPrimitiveResult(genCtx, castET.primitiveClass, sb, start);
+ genCtx.lastNullChecks = preservedNullChecks;
+ }
+ return;
+ }
+ if (!castET.isNumeric()) {
+ return;
+ }
+ // Wrap with the matching numeric helper. Re-record the primitive
+ // metadata so the comparison emits an unboxed compare.
+ final String inner = sb.substring(start);
+ sb.setLength(start);
+ switch (castET) {
+ case INT:
+ sb.append("h.toInt(").append(inner).append(")");
+ recordPrimitiveResult(genCtx, int.class, sb, start);
+ break;
+ case LONG:
+ sb.append("h.toLong(").append(inner).append(")");
+ recordPrimitiveResult(genCtx, long.class, sb, start);
+ break;
+ case FLOAT:
+ sb.append("h.toFloat(").append(inner).append(")");
+ recordPrimitiveResult(genCtx, float.class, sb, start);
+ break;
+ case DOUBLE:
+ sb.append("h.toDouble(").append(inner).append(")");
+ recordPrimitiveResult(genCtx, double.class, sb, start);
+ break;
+ default:
+ // unreachable — castET.isNumeric() checked above
+ sb.append(inner);
+ break;
+ }
+ }
+
+ /**
+ * Wrap an Object-typed expression in the right {@code h.toX()} helper
+ * for the chosen primitive comparison type. Falls back to
+ * {@code h.toLong} for non-numeric targets so the legacy behaviour is
+ * preserved when this is reached via the comparison fallback path.
+ */
+ private static String wrapAsPrimitive(final String objectExpr, final ExprType target) {
+ final String helper = target.runtimeHelper != null && target.isNumeric()
+ ? target.runtimeHelper : "h.toLong";
+ return helper + "(" + objectExpr + ")";
+ }
+
+ public static void generateConditionValue(final StringBuilder sb,
+ final TALConditionValue cv,
+ final TALGenCtx genCtx) {
+ if (cv instanceof TALStringConditionValue) {
+ sb.append('"')
+ .append(DslJavaSourceText.toLiteral(
+ ((TALStringConditionValue) cv).getValue()))
+ .append('"');
+ } else if (cv instanceof TALNumberConditionValue) {
+ final double val =
+ ((TALNumberConditionValue) cv).getValue();
+ sb.append("Long.valueOf(").append((long) val).append("L)");
+ } else if (cv instanceof TALBoolConditionValue) {
+ sb.append("Boolean.valueOf(")
+ .append(((TALBoolConditionValue) cv).isValue())
+ .append(")");
+ } else if (cv instanceof TALNullConditionValue) {
+ sb.append("null");
+ } else if (cv instanceof TALValueAccessConditionValue) {
+ generateValueAccessObj(sb,
+ ((TALValueAccessConditionValue) cv).getValue(),
+ null, genCtx);
+ }
+ }
+
+ /**
+ * Render a numeric RHS for a comparison operator. The literal is emitted
+ * in a form compatible with the LHS resolved type so the comparison stays
+ * in the LHS's primitive space — no defensive widening to long.
+ *
+ * <p>Examples (LHS in parens):
+ * <ul>
+ * <li>(int) {@code < 10000} → {@code 10000}</li>
+ * <li>(long) {@code < 10000} → {@code 10000L}</li>
+ * <li>(double) {@code < 1.5} → {@code 1.5d}</li>
+ * <li>(int) {@code < 1.5} → {@code 1.5d} — JLS will widen LHS to double</li>
+ * </ul>
+ */
+ public static void generateConditionValueNumeric(
+ final StringBuilder sb,
+ final TALConditionValue cv,
+ final Class<?> lhsType,
+ final TALGenCtx genCtx) {
+ if (cv instanceof TALNumberConditionValue) {
+ final TALNumberConditionValue ncv =
+ (TALNumberConditionValue) cv;
+ final String literal = ncv.getLiteral();
+ if (literal != null) {
+ sb.append(formatNumericLiteralForCompare(literal, lhsType));
+ } else {
+ // Synthesised value (no source text).
+ sb.append(formatDoubleAsLiteral(ncv.getValue(), lhsType));
+ }
+ } else if (cv instanceof TALValueAccessConditionValue) {
+ // RHS value access — emit the LHS-typed primitive form via the
+ // shared helper that picks between widening an already-primitive
+ // raw chain or wrapping a boxed object with h.toX().
+ final TALValueAccessConditionValue vacv =
+ (TALValueAccessConditionValue) cv;
+ sb.append(renderAsPrimitive(vacv.getValue(), vacv.getCastType(),
+ exprTypeFromClass(lhsType), genCtx));
+ } else {
+ sb.append("0L");
+ }
+ }
+
+ /**
+ * Render an operand into Java source representing a primitive of
+ * {@code targetType}. If {@link #emitOperandRespectingCast} produced
+ * an already-primitive expression (typed proto field, arithmetic
+ * result, paren-cast), widen it to the target — otherwise wrap the
+ * boxed object with the matching {@code h.toX()} helper. Shared
+ * between LHS rendering in {@link #generateNumericComparison} and
+ * RHS rendering in {@link #generateConditionValueNumeric}.
+ */
+ private static String renderAsPrimitive(
+ final TALValueAccess value,
+ final String cast,
+ final ExprType targetType,
+ final TALGenCtx genCtx) {
+ final StringBuilder buf = new StringBuilder();
+ emitOperandRespectingCast(buf, value, cast, genCtx);
+ final Class<?> resolved = genCtx.lastResolvedType;
+ if (isNumericPrimitiveClass(resolved) && genCtx.lastRawChain != null) {
+ return widenPrimitiveExpr(genCtx.lastRawChain,
+ exprTypeFromClass(resolved), targetType);
+ }
+ return wrapAsPrimitive(buf.toString(), targetType);
+ }
+
+ private static boolean isNumericPrimitiveClass(final Class<?> c) {
+ return c == int.class || c == long.class
+ || c == float.class || c == double.class;
+ }
+
+ private static String formatNumericLiteralForCompare(final String literal,
+ final Class<?> lhsType) {
+ final NumericLiteral parsed = NumericLiteral.parse(literal);
+ // Honour the user's declared literal type when wider than LHS;
+ // otherwise emit in the LHS form so the compare stays in that space.
+ final ExprType lhsExpr = exprTypeFromClass(lhsType);
+ final ExprType result = parsed.type.compareTo(lhsExpr) > 0 ? parsed.type : lhsExpr;
+ if (result == parsed.type) {
+ return parsed.javaText;
+ }
+ // Widen literal to LHS type via suffix change (no Java cast needed for
+ // numeric literals — the widened form is itself a valid literal).
+ return widenLiteralToType(parsed.javaText, parsed.type, result);
+ }
+
+ private static String widenLiteralToType(final String text,
+ final ExprType from,
+ final ExprType to) {
+ // Strip trailing suffix (if any) and re-emit in `to`.
+ String body = text;
+ final char last = body.isEmpty() ? 0 : body.charAt(body.length() - 1);
+ if (last == 'L' || last == 'F' || last == 'f' || last == 'd' || last == 'D') {
+ body = body.substring(0, body.length() - 1);
+ }
+ // Java treats `1`, `1.0`, and `1e0` as valid literals. We only need
+ // to append `.0` for INT-shaped bodies (no decimal AND no exponent)
+ // when widening to a fractional type — otherwise the body is
+ // already a valid float/double literal, just with a different suffix.
+ final boolean fractional = body.contains(".")
+ || body.contains("e") || body.contains("E");
+ switch (to) {
+ case LONG:
+ return body + "L";
+ case FLOAT:
+ return (fractional ? body : body + ".0") + "f";
+ case DOUBLE:
+ return fractional ? body : body + ".0";
+ case INT:
+ default:
+ return body;
+ }
+ }
+
+ private static String formatDoubleAsLiteral(final double value, final Class<?> lhsType) {
+ if (lhsType == double.class || lhsType == float.class) {
+ return Double.toString(value) + (lhsType == float.class ? "f" : "");
+ }
+ if (lhsType == long.class) {
+ return ((long) value) + "L";
+ }
+ return Long.toString((long) value);
+ }
+
+ // ==================== Value access ====================
+
+ /**
+ * Generates a value access with an explicit type cast.
+ *
+ * <p>TAL: {@code meta.latency as Long}
+ * <br>Generated: {@code h.toLong(h.mapVal("latency"))}
+ *
+ * <p>Supported cast types: String, Long, Integer, Boolean.
+ */
+ public static void generateCastedValueAccess(final StringBuilder sb,
+ final TALValueAccess value,
+ final String castType,
+ final TALGenCtx genCtx) {
+ // Each numeric cast produces a primitive expression; record the type
+ // and the raw chain so callers (numeric comparisons, arithmetic
+ // codegen) can skip a redundant h.toX() wrapper when the operand
+ // already matches the target primitive.
+ final ExprType castET = castToType(castType);
+ if (castET.runtimeHelper == null) {
+ // FQCN or no cast — emit the raw value access.
+ generateValueAccess(sb, value, genCtx);
+ return;
+ }
+ // Skip h.toStr(<string-literal>) — it's a no-op.
+ if (castET == ExprType.STRING && isPlainStringLiteral(value)) {
+ generateValueAccess(sb, value, genCtx);
+ return;
+ }
+ final int start = sb.length();
+ sb.append(castET.runtimeHelper).append("(");
+ generateValueAccess(sb, value, genCtx);
+ sb.append(")");
+ // Numeric casts produce a primitive — capture the raw chain so the
+ // caller can avoid the redundant unbox wrapper.
+ if (castET.isNumeric()) {
+ recordPrimitiveResult(genCtx, castET.primitiveClass, sb, start);
+ }
+ }
+
+ private static void recordPrimitiveResult(final TALGenCtx genCtx,
+ final Class<?> type,
+ final StringBuilder sb,
+ final int start) {
+ genCtx.lastResolvedType = type;
+ genCtx.lastRawChain = sb.substring(start);
+ genCtx.lastNullChecks = null;
+ }
+
+ /**
+ * Generates a value access that must produce a String result (used by
+ * tag assignments). For numeric / boolean casts wraps the conversion
+ * helper with {@code String.valueOf(...)}; for String (or unspecified)
+ * wraps with {@code h.toStr(...)} — except when the value is already
+ * a Java {@code String} literal, in which case the wrapper is elided
+ * since {@code h.toStr("llm")} just returns {@code "llm"}.
+ */
+ public static void generateStringValueAccess(final StringBuilder sb,
+ final TALValueAccess value,
+ final String castType,
+ final TALGenCtx genCtx) {
+ final ExprType castET = castToType(castType);
+ if (castET.isNumeric() || castET == ExprType.BOOLEAN) {
+ // String.valueOf(h.toX(value)) — primitive conversion then
+ // stringify. Drives off the runtime-helper field on ExprType
+ // instead of repeating a parallel switch.
+ sb.append("String.valueOf(").append(castET.runtimeHelper).append("(");
+ generateValueAccess(sb, value, genCtx);
+ sb.append("))");
+ return;
+ }
+ if (isPlainStringLiteral(value)) {
+ generateValueAccess(sb, value, genCtx);
+ return;
+ }
+ sb.append("h.toStr(");
+ generateValueAccess(sb, value, genCtx);
+ sb.append(")");
+ }
+
+ /**
+ * Generates a value access that produces an Object (boxed) result.
+ * Only applies String cast; other casts pass through as-is. Skips
+ * the {@code h.toStr()} wrapper when the value is already a Java
+ * String literal.
+ */
+ public static void generateValueAccessObj(final StringBuilder sb,
+ final TALValueAccess value,
+ final String castType,
+ final TALGenCtx genCtx) {
+ if ("String".equals(castType) && !isPlainStringLiteral(value)) {
+ sb.append("h.toStr(");
+ generateValueAccess(sb, value, genCtx);
+ sb.append(")");
+ } else {
+ generateValueAccess(sb, value, genCtx);
+ }
+ }
+
+ /**
+ * True when the operand is a bare Java String literal (no chain,
+ * no concat, no paren wrapping). For these the value-access codegen
+ * already emits a {@code String}, so a {@code h.toStr()} wrapper
+ * adds nothing.
+ */
+ private static boolean isPlainStringLiteral(final TALValueAccess value) {
+ return value.isStringLiteral()
+ && value.getChain().isEmpty()
+ && value.getConcatParts().isEmpty()
+ && value.getParenInner() == null;
+ }
+
+ /**
+ * Central dispatch for all TAL value-access expressions. Routes each
+ * expression to the appropriate codegen path based on its AST type.
+ *
+ * <p>Dispatch order:
+ * <ol>
+ * <li>String concatenation ({@code "..." + expr + "..."})</li>
+ * <li>Parenthesized expression ({@code (expr as Type).chain})</li>
+ * <li>Standalone {@code tag("KEY")} function call</li>
+ * <li>String/number literals</li>
+ * <li>{@code ProcessRegistry.method(...)} static calls</li>
+ * <li>{@code log.X.Y} direct proto getter chains</li>
+ * <li>{@code parsed.X.Y} with compile-time type analysis</li>
+ * <li>{@code def} variable reference with method chain</li>
+ * <li>Fallback: compile-time error</li>
+ * </ol>
+ *
+ * <p>Note: standalone {@code tag("KEY")} and {@code parsed.tag("KEY")}
+ * are different AST structures. {@code tag("KEY")} is a top-level
+ * function call handled here; {@code parsed.tag("KEY")} is a
+ * {@code parsed}-prefixed chain where {@code tag("KEY")} appears as a
+ * MethodSegment, handled by the resolver's input-root access.
+ */
+ public static void generateValueAccess(final StringBuilder sb,
+ final TALValueAccess value,
+ final TALGenCtx genCtx) {
+ genCtx.clearExtraLogResult();
+
+ // Handle binary expressions (term1 OP term2 OP ...). The decision is
+ // delegated to generateBinaryExpression, which performs JLS-style type
+ // inference and emits either Java arithmetic, string concatenation, or a
+ // compile-time error.
+ if (!value.getConcatParts().isEmpty()) {
+ generateBinaryExpression(sb, value.getConcatParts(),
+ value.getConcatOps(), genCtx);
+ return;
+ }
+
+ // Handle parenthesized expression: (innerExpr as Type).chain...
+ if (value.getParenInner() != null) {
+ generateParenAccess(sb, value, genCtx);
+ return;
+ }
+
+ // Built-in function calls are TAL's own vocabulary: attr(), resource(), component() and the rest.
+ // The resolver claims the name or lets the generic paths below continue.
+ if (value.getFunctionCallName() != null
+ && genCtx.resolver.generateFunctionCall(sb, value, genCtx)) {
+ return;
+ }
+
+ // Handle string/number literals
+ if (value.isStringLiteral() && value.getChain().isEmpty()) {
+ sb.append("\"").append(DslJavaSourceText.toLiteral(value.getSegments().get(0)))
+ .append("\"");
+ return;
+ }
+ if (value.isNumberLiteral() && value.getChain().isEmpty()) {
+ final String num = value.getSegments().get(0);
+ final NumericLiteral lit = NumericLiteral.parse(num);
+ switch (lit.type) {
+ case DOUBLE:
+ sb.append("Double.valueOf(").append(lit.javaText).append(")");
+ break;
+ case FLOAT:
+ sb.append("Float.valueOf(").append(lit.javaText).append(")");
+ break;
+ case LONG:
+ sb.append("Long.valueOf(").append(lit.javaText).append(")");
+ break;
+ case INT:
+ default:
+ sb.append("Integer.valueOf(").append(lit.javaText).append(")");
+ break;
+ }
+ return;
+ }
+
+ if (value.isStaticRef() && genCtx.resolver.generateStaticRefAccess(sb, value, genCtx)) {
+ return;
+ }
+
+ final List<? extends TALValueAccessSegment> chain = value.getChain();
+
+ if (value.isMetaRef()) {
+ genCtx.resolver.generateMetaRootAccess(sb, chain, genCtx);
+ return;
+ }
+
+ if (value.isInputRef()) {
+ genCtx.resolver.generateInputRootAccess(sb, chain, genCtx);
+ return;
+ }
+
+ // Check for def variable reference
+ if (!value.getSegments().isEmpty()) {
+ final String primaryName = value.getSegments().get(0);
+ final TALLocalVar localVar =
+ genCtx.localVars.get(primaryName);
+ if (localVar != null) {
+ TALDefCodegen.generateDefVarChain(sb, localVar, chain, genCtx);
+ return;
+ }
+ }
+
+ // No matching codegen path — fail at compile time instead of silently
+ // generating null.
+ if (chain.isEmpty()) {
+ final String desc = value.getFunctionCallName() != null
+ ? "function call '" + value.getFunctionCallName() + "(...)'"
+ : "expression '" + value.getSegments() + "'";
+ throw new IllegalArgumentException(
+ "Cannot resolve " + desc + " — no matching codegen path. "
+ + genCtx.resolver.describeContext());
+ }
+ // A bare chain with no recognized root reads the input root, which is what an unqualified field means.
+ genCtx.resolver.generateInputRootAccess(sb, chain, genCtx);
+ }
+
+ // ==================== Parenthesized expression ====================
+
+ /**
+ * Generates code for a parenthesized expression with optional type cast
+ * and method chain.
+ *
+ * <p>TAL: {@code (attr("db.system.name") as String).trim()}
+ * <br>Generated: {@code h.toStr(h.mapVal("component")).trim()}
+ */
+ public static void generateParenAccess(final StringBuilder sb,
+ final TALValueAccess value,
+ final TALGenCtx genCtx) {
+ // Generate the inner expression with cast
+ final String castType = value.getParenCast();
+ final StringBuilder inner = new StringBuilder();
+ if (castType != null) {
+ generateCastedValueAccess(inner, value.getParenInner(), castType, genCtx);
+ } else {
+ generateValueAccess(inner, value.getParenInner(), genCtx);
+ }
+
+ // Apply chain segments (methods, fields, index access)
+ String current = inner.toString();
+ for (final TALValueAccessSegment seg : value.getChain()) {
+ if (seg instanceof TALMethodSegment) {
+ current = appendMethodSegment(current,
+ (TALMethodSegment) seg, genCtx);
+ } else if (seg instanceof TALIndexSegment) {
+ current = current + "["
+ + ((TALIndexSegment) seg).getIndex() + "]";
+ } else if (seg instanceof TALFieldSegment) {
+ final TALFieldSegment fs =
+ (TALFieldSegment) seg;
+ if (fs.isSafeNav()) {
+ current = "(" + current + " == null ? null : "
+ + current + "." + fs.getName() + ")";
+ } else {
+ current = current + "." + fs.getName();
+ }
+ }
+ }
+ sb.append(current);
+ }
+
+ /**
+ * Generates a reflection-based getter chain on a typed root object, which is what every DSL root that
+ * resolves to a class needs: {@code span?.status?.message} on the OTLP span, {@code meta.latency} on the
+ * metadata view.
+ *
+ * <p>Each getter call is validated at compile time via reflection. Safe
+ * navigation ({@code ?.}) generates null checks. Intermediate results
+ * are cached in local variables ({@code _t0}, {@code _t1}, ...) to avoid
+ * redundant getter calls when the same chain prefix appears multiple times.
+ */
+ /**
+ * The same reflective getter walk as {@link #generateTypedChainAccess}, emitted inline instead of through
+ * hoisted variables.
+ *
+ * <p>Caching a chain into a variable declared at the top of the method is only sound while the root cannot
+ * change during the rule. {@code meta} can: an extractor's {@code service}, {@code endpoint} and
+ * {@code layer} statements overwrite it, and a cached read would hand later statements the value from before
+ * the overwrite.
+ *
+ * @param fieldSegments the field accesses applied to the root
+ * @param rootType the root's class, walked by reflection so a wrong field name fails at compile
+ * @param rootExpr the Java expression producing the root
+ * @param genCtx the generation context
+ * @return the Java expression reading the chain
+ */
+ public static String generateInlineChainAccess(
+ final List<? extends TALFieldSegment> fieldSegments,
+ final Class<?> rootType,
+ final String rootExpr,
+ final TALGenCtx genCtx) {
+ if (fieldSegments.isEmpty()) {
+ return rootExpr;
+ }
+ String current = rootExpr;
+ Class<?> currentType = rootType;
+ for (final TALFieldSegment seg : fieldSegments) {
+ final String field = seg.getName();
+ final String getterName = "get" + Character.toUpperCase(field.charAt(0)) + field.substring(1);
+ Method getter;
+ try {
+ getter = currentType.getMethod(getterName);
+ } catch (NoSuchMethodException e) {
+ // A boolean field's accessor is isX(), which is how meta.root reads.
+ final String isName = "is" + Character.toUpperCase(field.charAt(0)) + field.substring(1);
+ try {
+ getter = currentType.getMethod(isName);
+ } catch (NoSuchMethodException e2) {
+ throw new IllegalArgumentException(
+ "Cannot resolve " + currentType.getSimpleName() + "." + getterName + "() for type "
+ + rootType.getName() + ". Check the field path in the TAL rule.");
+ }
+ }
+ current = current + "." + getter.getName() + "()";
+ currentType = getter.getReturnType();
+ }
+ genCtx.lastResolvedType = currentType;
+ genCtx.lastRawChain = current;
+ genCtx.lastNullChecks = null;
+ if (currentType.isPrimitive()) {
+ final String boxName = TALCodegenHelper.boxTypeName(currentType);
+ return boxName == null ? current : boxName + ".valueOf(" + current + ")";
+ }
+ return current;
+ }
+
+ public static String generateTypedChainAccess(
+ final List<? extends TALFieldSegment> fieldSegments,
+ final Class<?> rootType,
+ final String rootExpr,
+ final boolean rootCanBeNull,
+ final TALGenCtx genCtx) {
+ genCtx.usedProtoAccess = true;
+
+ if (fieldSegments.isEmpty()) {
+ return rootExpr;
+ }
+
+ final String typeName = rootType.getName();
+ final StringBuilder chainKey = new StringBuilder();
+ String prevVar = rootExpr;
+ Class<?> currentType = rootType;
+ boolean prevCanBeNull = rootCanBeNull;
+
+ for (int i = 0; i < fieldSegments.size(); i++) {
+ final TALFieldSegment seg = fieldSegments.get(i);
+ final String field = seg.getName();
+ final String getterName = "get" + Character.toUpperCase(field.charAt(0))
+ + field.substring(1);
+
+ final Method getter;
+ try {
+ getter = currentType.getMethod(getterName);
+ } catch (NoSuchMethodException e) {
+ throw new IllegalArgumentException(
+ "Cannot resolve getter " + currentType.getSimpleName()
+ + "." + getterName + "() for type "
+ + typeName + ". Check the field path in the TAL rule.");
+ }
+ final Class<?> returnType = getter.getReturnType();
+
+ if (chainKey.length() > 0) {
+ chainKey.append(".");
+ }
+ chainKey.append(field);
+ final String key = chainKey.toString();
+ final boolean isLast = i == fieldSegments.size() - 1;
+
+ // Primitive final segment: return inline expression, no variable
+ if (isLast && returnType.isPrimitive()) {
+ final String rawAccess = prevVar + "." + getterName + "()";
+ genCtx.lastResolvedType = returnType;
+ genCtx.lastRawChain = rawAccess;
+ final String boxName = TALCodegenHelper.boxTypeName(returnType);
+ if (seg.isSafeNav() && prevCanBeNull) {
+ genCtx.lastNullChecks = prevVar + " == null";
+ return "(" + prevVar + " == null ? null : "
+ + boxName + ".valueOf(" + rawAccess + "))";
+ } else {
+ genCtx.lastNullChecks = null;
+ return boxName + ".valueOf(" + rawAccess + ")";
+ }
+ }
+
+ // Reuse existing variable (dedup)
+ final String existingVar = genCtx.protoVars.get(key);
+ if (existingVar != null) {
+ prevVar = existingVar;
+ currentType = returnType;
+ prevCanBeNull = true;
+ continue;
+ }
+
+ // Create new local variable declaration
+ final String newVar = "_t" + genCtx.protoVarCounter++;
+ final String returnTypeName = returnType.getName();
+ if (seg.isSafeNav() && prevCanBeNull) {
+ genCtx.protoVarDecls.append(" ").append(returnTypeName)
+ .append(" ").append(newVar).append(" = ")
+ .append(prevVar).append(" == null ? null : ")
+ .append(prevVar).append(".").append(getterName).append("();\n");
+ prevCanBeNull = true;
+ } else {
+ genCtx.protoVarDecls.append(" ").append(returnTypeName)
+ .append(" ").append(newVar).append(" = ")
+ .append(prevVar).append(".").append(getterName).append("();\n");
+ prevCanBeNull = !returnType.isPrimitive();
+ }
+ genCtx.protoVars.put(key, newVar);
+ genCtx.protoLvtVars.add(new String[]{
+ newVar, "L" + returnTypeName.replace('.', '/') + ";"
+ });
+
+ prevVar = newVar;
+ currentType = returnType;
+ }
+
+ // Non-primitive final result — null checks are in declarations
+ genCtx.lastResolvedType = currentType;
+ genCtx.lastRawChain = prevVar;
+ genCtx.lastNullChecks = null;
+ return prevVar;
+ }
+
+ // ==================== Utility methods ====================
+
+ // ==================== Binary expression codegen ====================
+
+ /**
+ * Parsed representation of a NUMBER literal token. Carries the inferred
+ * Java type and the literal text trimmed/suffixed for direct emission as
+ * Java source.
+ */
+ private static final class NumericLiteral {
+ final ExprType type;
+ /** Java-source representation, e.g. "10000", "10000L", "1.5", "1.5f". */
+ final String javaText;
+
+ private NumericLiteral(final ExprType type, final String javaText) {
+ this.type = type;
+ this.javaText = javaText;
+ }
+
+ static NumericLiteral parse(final String numText) {
+ String t = numText;
+ char suffix = 0;
+ if (!t.isEmpty()) {
+ final char last = t.charAt(t.length() - 1);
+ if (last == 'L' || last == 'l' || last == 'F' || last == 'f'
+ || last == 'D' || last == 'd') {
+ suffix = last;
+ t = t.substring(0, t.length() - 1);
+ }
+ }
+ final boolean fractional = t.contains(".") || t.contains("e") || t.contains("E");
+ switch (suffix) {
+ case 'L':
+ case 'l':
+ // Magnitude-overflow on an L-suffixed literal is caught
+ // by Javassist with a clear "long literal too large"
+ // diagnostic referencing the same token the user wrote,
+ // so we don't duplicate that check here.
+ return new NumericLiteral(ExprType.LONG, t + "L");
+ case 'F':
+ case 'f':
+ return new NumericLiteral(ExprType.FLOAT,
+ (fractional ? t : (t + ".0")) + "f");
+ case 'D':
+ case 'd':
+ return new NumericLiteral(ExprType.DOUBLE,
+ (fractional ? t : (t + ".0")) + "d");
+ default:
+ if (fractional) {
+ return new NumericLiteral(ExprType.DOUBLE, t);
+ }
+ // Bare integer literal — INT if it fits, else LONG.
+ // Magnitude overflow beyond `long` is caught by
+ // Javassist when it parses our generated `<digits>L`
+ // token, so we don't pre-validate the long range here.
+ try {
+ Integer.parseInt(t);
+ return new NumericLiteral(ExprType.INT, t);
+ } catch (NumberFormatException ignoredInt) {
+ return new NumericLiteral(ExprType.LONG, t + "L");
+ }
+ }
+ }
+ }
+
+ /**
+ * Returns the JLS-style binary numeric promotion result for the two operand
+ * types. Both must be numeric; otherwise this is a programmer bug (the
+ * caller is responsible for the non-numeric error path).
+ */
+ private static ExprType promote(final ExprType a, final ExprType b) {
+ if (a == ExprType.DOUBLE || b == ExprType.DOUBLE) {
+ return ExprType.DOUBLE;
+ }
+ if (a == ExprType.FLOAT || b == ExprType.FLOAT) {
+ return ExprType.FLOAT;
+ }
+ if (a == ExprType.LONG || b == ExprType.LONG) {
+ return ExprType.LONG;
+ }
+ return ExprType.INT;
+ }
+
+ /**
+ * Compile-time inference of an operand's Java type. Operates on the same
+ * AST that codegen will subsequently emit, so the result is consistent.
+ */
+ private static ExprType inferType(final TALValueAccess part,
+ final TALGenCtx genCtx) {
+ if (part == null) {
+ return ExprType.UNKNOWN;
+ }
+ if (part.isStringLiteral()) {
+ return ExprType.STRING;
+ }
+ if (part.isNumberLiteral() && part.getChain().isEmpty()) {
+ return NumericLiteral.parse(part.getSegments().get(0)).type;
+ }
+ // (expr as Cast) primary — only trustable when no further chain is applied.
+ if (part.getParenInner() != null && part.getChain().isEmpty()) {
+ if (part.getParenCast() != null) {
+ return castToType(part.getParenCast());
+ }
+ // Pure grouping (no cast): the parens just preserve precedence.
+ return inferType(part.getParenInner(), genCtx);
+ }
+ // Nested binary expression: recompute via its parts/ops.
+ if (!part.getConcatParts().isEmpty()) {
+ return inferBinaryType(part.getConcatParts(), part.getConcatOps(), genCtx);
+ }
+ // def variable with a known resolved type.
+ if (!part.getSegments().isEmpty()) {
+ final TALLocalVar lv =
+ genCtx.localVars.get(part.getSegments().get(0));
+ if (lv != null && part.getChain().isEmpty()) {
+ return exprTypeFromClass(lv.resolvedType);
+ }
+ }
+ // A built-in's return type is the DSL's to declare; without it the expression would fall back to string
+ // concatenation and a numeric built-in could not take part in arithmetic.
+ if (part.getFunctionCallName() != null) {
+ final ExprType declared = genCtx.resolver.functionReturnType(part.getFunctionCallName());
+ if (declared != null) {
+ return declared;
+ }
+ }
+ // parsed.* — when the rule has a typed inputType (no JSON/YAML/TEXT
+ // parser), walk the proto getter chain via reflection so primitive
+ // numeric leaves participate in arithmetic and don't fall through
+ // to string concat. Mirrors {@link #generateTypedChainAccess} but
+ // does not emit code or local variables.
+ if (part.isInputRef()
+ && genCtx.resolver.isTypedInputActive()
+ && genCtx.inputType != null) {
+ final Class<?> primitive = walkProtoChainPrimitiveType(
+ part.getChain(), genCtx.inputType);
+ if (primitive != null) {
+ final ExprType t = exprTypeFromClass(primitive);
+ // Only echo back primitive numeric / boolean leaves —
+ // non-primitive return types fall through to UNKNOWN
+ // (handled by the original chain-walk codegen at runtime).
+ if (t.isNumeric() || t == ExprType.BOOLEAN) {
+ return t;
+ }
+ }
+ }
+ return ExprType.UNKNOWN;
+ }
+
+ /**
+ * Map a Java {@link Class} (primitive or wrapper) to the matching
+ * {@link ExprType}. Used when type information arrives as a Class —
+ * from {@code def} variable resolution or proto-chain reflection —
+ * and replaces what was two parallel if/else ladders.
+ */
+ private static ExprType exprTypeFromClass(final Class<?> c) {
+ if (c == int.class || c == Integer.class) {
+ return ExprType.INT;
+ }
+ if (c == long.class || c == Long.class) {
+ return ExprType.LONG;
+ }
+ if (c == float.class || c == Float.class) {
+ return ExprType.FLOAT;
+ }
+ if (c == double.class || c == Double.class) {
+ return ExprType.DOUBLE;
+ }
+ if (c == String.class) {
+ return ExprType.STRING;
+ }
+ if (c == boolean.class || c == Boolean.class) {
+ return ExprType.BOOLEAN;
+ }
+ return ExprType.OBJECT;
+ }
+
+ /**
+ * Walk a {@code parsed.*} field-segment chain over the typed proto root
+ * via reflection, returning the primitive return type of the final getter
+ * if the chain is field-only and ends at a primitive accessor; {@code null}
+ * otherwise.
+ */
+ private static Class<?> walkProtoChainPrimitiveType(
+ final List<? extends TALValueAccessSegment> chain,
+ final Class<?> rootType) {
+ if (chain == null || chain.isEmpty()) {
+ return null;
+ }
+ Class<?> currentType = rootType;
+ for (int i = 0; i < chain.size(); i++) {
+ final TALValueAccessSegment seg = chain.get(i);
+ if (!(seg instanceof TALFieldSegment)) {
+ return null;
+ }
+ final String field = ((TALFieldSegment) seg).getName();
+ final String getter = "get" + Character.toUpperCase(field.charAt(0))
+ + field.substring(1);
+ try {
+ currentType = currentType.getMethod(getter).getReturnType();
+ } catch (NoSuchMethodException e) {
+ return null;
+ }
+ }
+ return currentType.isPrimitive() ? currentType : null;
+ }
+
+ private static ExprType castToType(final String cast) {
+ if ("Integer".equals(cast)) {
+ return ExprType.INT;
+ }
+ if ("Long".equals(cast)) {
+ return ExprType.LONG;
+ }
+ if ("Float".equals(cast)) {
+ return ExprType.FLOAT;
+ }
+ if ("Double".equals(cast)) {
+ return ExprType.DOUBLE;
+ }
+ if ("String".equals(cast)) {
+ return ExprType.STRING;
+ }
+ if ("Boolean".equals(cast)) {
+ return ExprType.BOOLEAN;
+ }
+ return ExprType.UNKNOWN;
+ }
+
+ /**
+ * Walk the operand list applying JLS promotion left-to-right, treating any
+ * {@code +} that touches a String operand as string concat (which sticks).
+ */
+ private static ExprType inferBinaryType(
+ final List<? extends TALValueAccess> parts,
+ final List<BinaryOp> ops,
+ final TALGenCtx genCtx) {
+ ExprType acc = inferType(parts.get(0), genCtx);
+ for (int i = 1; i < parts.size(); i++) {
+ final ExprType rhs = inferType(parts.get(i), genCtx);
+ final BinaryOp op = ops.get(i - 1);
+ if (op == BinaryOp.PLUS
+ && (acc == ExprType.STRING || rhs == ExprType.STRING)) {
+ acc = ExprType.STRING;
+ continue;
+ }
+ if (acc.isNumeric() && rhs.isNumeric()) {
+ acc = promote(acc, rhs);
+ continue;
+ }
+ // Anything else for + (object + object) → fallback to string concat
+ // (preserves long-standing behaviour for `tag("a") + tag("b")` etc.).
+ if (op == BinaryOp.PLUS) {
+ acc = ExprType.STRING;
+ continue;
+ }
+ // - * / on non-numeric — caller emits a compile error.
+ return ExprType.UNKNOWN;
+ }
+ return acc;
+ }
+
+ /**
+ * Top-level binary-expression codegen. Mirrors Java's left-to-right
+ * evaluation: adjacent numeric operands accumulate into a primitive
+ * arithmetic expression; once a String operand appears, every subsequent
+ * {@code +} becomes string concatenation. This preserves the semantic
+ * difference between {@code 1 + 2 + "x"} (= {@code "3x"}) and
+ * {@code "" + 1 + 2 + "x"} (= {@code "12x"}).
+ */
+ private static void generateBinaryExpression(
+ final StringBuilder sb,
+ final List<? extends TALValueAccess> parts,
+ final List<BinaryOp> ops,
+ final TALGenCtx genCtx) {
+ // Render the first operand and seed the accumulator with its type.
+ ExprType accType = inferType(parts.get(0), genCtx);
+ final StringBuilder accBuf = new StringBuilder();
+ appendOperandRaw(accBuf, parts.get(0), accType, genCtx);
+ String accExpr = accBuf.toString();
+
+ for (int i = 1; i < parts.size(); i++) {
+ final BinaryOp op = ops.get(i - 1);
+ final ExprType rhsType = inferType(parts.get(i), genCtx);
+ final StringBuilder rhsBuf = new StringBuilder();
+ appendOperandRaw(rhsBuf, parts.get(i), rhsType, genCtx);
+ final String rhsExpr = rhsBuf.toString();
+
+ if (accType.isNumeric() && rhsType.isNumeric()) {
+ final ExprType promoted = promote(accType, rhsType);
+ final String widenedAcc = widenPrimitiveExpr(accExpr, accType, promoted);
+ final String widenedRhs = widenPrimitiveExpr(rhsExpr, rhsType, promoted);
+ accExpr = "(" + widenedAcc + " " + op.symbol() + " " + widenedRhs + ")";
+ accType = promoted;
+ continue;
+ }
+ if (op != BinaryOp.PLUS) {
+ throw new IllegalArgumentException(
+ "Operator '" + op.symbol() + "' requires numeric operands; "
+ + "got non-numeric expression. Cast operands with "
+ + "'as Integer/Long/Float/Double' to enable arithmetic.");
+ }
+ // String concat path. Java's `+` only accepts the chain when
+ // at least one operand is statically a String; otherwise (e.g.
+ // `int + Object` or `Object + Object`) the source won't even
+ // compile. Prepend a leading `""` whenever neither side is
+ // statically String at the transition point. The numeric
+ // arithmetic prefix is already in parens, so `("" + (1 + 2))`
+ // still computes the sum first ("3"), preserving the
+ // semantics of `1 + 2 + parsed.x` (= "3<obj>").
+ if (accType != ExprType.STRING && rhsType != ExprType.STRING) {
+ accExpr = "\"\" + " + accExpr;
+ }
+ accExpr = accExpr + " + " + rhsExpr;
+ accType = ExprType.STRING;
+ }
+
+ if (accType.isNumeric()) {
+ // Expose the primitive form so the caller (numeric comparison)
+ // can avoid h.toX() unboxing; emit a boxed form into sb for
+ // Object contexts (tag assignments, def initialisers, ...).
+ genCtx.lastResolvedType = accType.primitiveClass;
+ genCtx.lastRawChain = accExpr;
+ genCtx.lastNullChecks = null;
+ sb.append(accType.wrapperName).append(".valueOf(").append(accExpr).append(")");
+ } else {
+ // Non-numeric end state: a String concatenation. Update the
+ // genCtx metadata explicitly — otherwise a stale numeric
+ // resolved type from an inner operand would leak out and
+ // mis-type things like `def msg = "count=" + (tag("n") as Integer)`,
+ // which the def codegen reads from lastResolvedType to declare
+ // the local variable.
+ genCtx.lastResolvedType = String.class;
+ genCtx.lastRawChain = null;
+ genCtx.lastNullChecks = null;
+ sb.append(accExpr);
+ }
+ }
+
+ /**
+ * Render a single operand for use inside a binary expression — returning
+ * its raw form (primitive expression for numeric operands, Object/String
+ * form otherwise). Number literals emit with their declared suffix,
+ * paren-cast operands emit through the matching helper, paren-grouping
+ * recurses into the inner expression, and nested binary expressions
+ * reuse the inner accumulator's raw chain when numeric.
+ */
+ private static void appendOperandRaw(final StringBuilder sb,
+ final TALValueAccess part,
+ final ExprType partType,
+ final TALGenCtx genCtx) {
+ if (part.isNumberLiteral() && part.getChain().isEmpty()) {
+ sb.append(NumericLiteral.parse(part.getSegments().get(0)).javaText);
+ return;
+ }
+ if (part.getParenInner() != null && part.getParenCast() != null
+ && part.getChain().isEmpty() && partType.isNumeric()) {
+ generateCastedValueAccess(sb, part.getParenInner(),
+ partType.wrapperName, genCtx);
+ return;
+ }
+ if (part.getParenInner() != null && part.getParenCast() == null
+ && part.getChain().isEmpty()) {
+ final StringBuilder inner = new StringBuilder();
+ generateValueAccessObj(inner, part.getParenInner(), null, genCtx);
+ final Class<?> resolved = genCtx.lastResolvedType;
+ if (partType.isNumeric() && resolved != null && resolved.isPrimitive()
+ && genCtx.lastRawChain != null) {
+ sb.append(genCtx.lastRawChain);
+ } else {
+ sb.append(inner);
+ }
+ return;
+ }
+ if (!part.getConcatParts().isEmpty()) {
+ final StringBuilder inner = new StringBuilder();
+ generateBinaryExpression(inner, part.getConcatParts(),
+ part.getConcatOps(), genCtx);
+ if (partType.isNumeric() && genCtx.lastRawChain != null) {
+ sb.append(genCtx.lastRawChain);
+ } else {
+ sb.append(inner);
+ }
+ return;
+ }
+ if (partType.isNumeric()) {
+ // Render the operand natively, then prefer the primitive raw
+ // chain when one is available — typed-proto safe-nav primitive
+ // leaves go through generateTypedChainAccess which sets
+ // lastRawChain to the unboxed access. Wrapping the boxed
+ // null-safe form with `h.toX()` would silently turn a missing
+ // chain into 0 (h.toInt(null) = 0) instead of letting the
+ // null guard surface — see {@link #generateTypedChainAccess}.
+ // Falls back to {@code h.toX(...)} for untyped operands such
+ // as bare {@code tag()} or {@code parsed.x} on a JSON parser.
+ final StringBuilder buf = new StringBuilder();
+ generateValueAccess(buf, part, genCtx);
+ if (genCtx.lastRawChain != null
+ && isNumericPrimitiveClass(genCtx.lastResolvedType)) {
+ sb.append(widenPrimitiveExpr(genCtx.lastRawChain,
+ exprTypeFromClass(genCtx.lastResolvedType), partType));
+ } else {
+ sb.append(wrapAsPrimitive(buf.toString(), partType));
+ }
+ } else {
+ generateValueAccess(sb, part, genCtx);
+ }
+ }
+
+
+ /**
+ * Appends a method call segment to the current expression chain.
+ * Handles safe-navigation ({@code ?.method()}) by wrapping in a null
+ * guard. Special-cases {@code ?.toString()} and {@code ?.trim()} to
+ * use helper methods for null-safe behavior.
+ */
+ public static String appendMethodSegment(final String current,
+ final TALMethodSegment ms,
+ final TALGenCtx genCtx) {
+ final String mn = ms.getName();
+ final String args = ms.getArguments().isEmpty()
+ ? "" : generateMethodArgs(ms.getArguments(), genCtx);
+ if (ms.isSafeNav()) {
+ // Special-cased helpers for common safe-nav methods on Object
+ if ("toString".equals(mn)) {
+ return "h.toString(" + current + ")";
+ } else if ("trim".equals(mn)) {
+ return "h.trim(" + current + ")";
+ }
+ // General safe-nav: null guard with ternary
+ return "(" + current + " == null ? null : "
+ + current + "." + mn + "(" + args + "))";
+ } else {
+ return current + "." + mn + "(" + args + ")";
+ }
+ }
+
+ /**
+ * Generates the argument list for a method call. Handles string literals,
+ * number literals, boolean/null literals, and def variable references.
+ */
+ public static String generateMethodArgs(
+ final List<? extends TALFunctionArg> args,
+ final TALGenCtx genCtx) {
+ final StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < args.size(); i++) {
+ if (i > 0) {
+ sb.append(", ");
+ }
+ final TALFunctionArg arg = args.get(i);
+ final TALValueAccess va = arg.getValue();
+ // Honour the user's declared cast on the argument
+ // (`substring(tag("n") as Integer)`) — generateCastedValueAccess
+ // emits the matching `h.toX(...)` helper so the call site
+ // sees the requested primitive type, allowing Javassist to
+ // resolve primitive-arg overloads.
+ final String argCast = arg.getCastType();
+ if (argCast != null) {
+ generateCastedValueAccess(sb, va, argCast, genCtx);
+ continue;
+ }
+ // Binary expression node — happens when the user writes
+ // `foo.bar(1 + 2)` etc. Render via the standard value-access
+ // path so arithmetic / string-concat / paren grouping all
+ // work. When the result is a numeric primitive, use the raw
+ // chain form (`(1 + 2)`) instead of the boxed wrapper
+ // (`Integer.valueOf(...)`) — Javassist doesn't auto-unbox
+ // when matching method-arg overloads, so a primitive-arg
+ // method like {@code String.substring(int)} would otherwise
+ // fail to resolve.
+ if (!va.getConcatParts().isEmpty()) {
+ final StringBuilder buf = new StringBuilder();
+ generateValueAccess(buf, va, genCtx);
+ if (genCtx.lastRawChain != null) {
+ sb.append(genCtx.lastRawChain);
+ } else {
+ sb.append(buf);
+ }
+ continue;
+ }
+ if (va.isStringLiteral()) {
+ sb.append("\"").append(DslJavaSourceText.toLiteral(
+ va.getSegments().get(0))).append("\"");
+ } else if (va.isNumberLiteral()) {
+ // Normalise the literal text — e.g. `1f` → `1.0f`, `1d`
+ // → `1.0` — so the emitted Java is unambiguous.
+ sb.append(NumericLiteral.parse(va.getSegments().get(0)).javaText);
+ } else if (!va.getSegments().isEmpty()) {
+ final String text = va.getSegments().get(0);
+ if ("true".equals(text) || "false".equals(text)
+ || "null".equals(text)) {
+ // Boolean or null literal
+ sb.append(text);
+ } else if (genCtx != null
+ && genCtx.localVars.containsKey(text)) {
+ // Local def variable reference
+ sb.append(genCtx.localVars.get(text).javaVarName);
+ } else if (genCtx != null
+ && (va.isInputRef() || va.isMetaRef()
+ || !va.getChain().isEmpty()
+ || va.getFunctionCallName() != null
+ || va.getParenInner() != null)) {
+ // tag(), parsed.*, log.*, paren-cast, or any value
+ // access with a chain — render via the standard path.
+ generateValueAccess(sb, va, genCtx);
+ } else {
+ throw new IllegalArgumentException(
+ "Unknown identifier used as method argument: '" + text + "'");
+ }
+ } else {
+ sb.append("null");
+ }
+ }
+ return sb.toString();
+ }
+}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/BinaryOp.java
similarity index 52%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/BinaryOp.java
index e3c3eedfc1..6e18ee8aab 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/BinaryOp.java
@@ -13,24 +13,29 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+/**
+ * Binary arithmetic or concatenation operator joining adjacent operands of a value expression. For N operands
+ * there are N-1 operators, {@code ops[i]} joining {@code parts[i]} and {@code parts[i + 1]}. Precedence is already
+ * encoded by the parser, which nests multiplicative expressions inside additive operands. The symbol is the Java
+ * source token, so the codegen needs no parallel switch.
+ */
+public enum BinaryOp {
+ PLUS("+"),
+ MINUS("-"),
+ STAR("*"),
+ SLASH("/");
- String getComponentName(int componentId);
+ private final String symbol;
- String getServerNameBasedOnComponent(int componentId);
+ BinaryOp(final String symbol) {
+ this.symbol = symbol;
+ }
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+ public String symbol() {
+ return symbol;
+ }
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/CompareOp.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/CompareOp.java
index e3c3eedfc1..99ff465637 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/CompareOp.java
@@ -13,24 +13,13 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * The comparison operators a DSL condition may use.
+ */
+public enum CompareOp {
+ EQ, NEQ, GT, LT, GTE, LTE
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/LogicalOp.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/LogicalOp.java
index e3c3eedfc1..78477e389a 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/LogicalOp.java
@@ -13,24 +13,13 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * The operators joining two DSL conditions.
+ */
+public enum LogicalOp {
+ AND, OR
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALBoolConditionValue.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALBoolConditionValue.java
index e3c3eedfc1..8376983e3d 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALBoolConditionValue.java
@@ -13,24 +13,13 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * A boolean literal on the right of a comparison.
+ */
+public interface TALBoolConditionValue extends TALConditionValue {
+ boolean isValue();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALComparisonCondition.java
similarity index 61%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALComparisonCondition.java
index e3c3eedfc1..e460898475 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALComparisonCondition.java
@@ -13,24 +13,22 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * A comparison between a value expression and a condition value, {@code left op right}.
+ */
+public interface TALComparisonCondition extends TALCondition {
+ TALValueAccess getLeft();
/**
- * @return true if the given componentB has high priority
+ * @return the {@code as Type} cast written on the left operand, or null
*/
- boolean compare(int componentA, int componentB);
+ String getLeftCast();
+
+ CompareOp getOp();
+
+ TALConditionValue getRight();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALCondition.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALCondition.java
index e3c3eedfc1..e8ef62fb43 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALCondition.java
@@ -13,24 +13,12 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * The condition of an {@code if}, as the shared condition codegen sees it.
+ */
+public interface TALCondition {
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALConditionValue.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALConditionValue.java
index e3c3eedfc1..2496a36466 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALConditionValue.java
@@ -13,24 +13,12 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * The right-hand side of a comparison.
+ */
+public interface TALConditionValue {
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALDefStatement.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALDefStatement.java
index e3c3eedfc1..fa8ab8263d 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALDefStatement.java
@@ -13,24 +13,22 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
+/**
+ * A {@code def} statement: a local variable whose type is inferred from its initializer. The declaration is
+ * hoisted to the top of the generated method, so a second {@code def} of the same name assigns to the same
+ * variable rather than shadowing it.
+ */
+public interface TALDefStatement {
+ String getVarName();
- String getServerNameBasedOnComponent(int componentId);
+ TALValueAccess getInitializer();
/**
- * @return true if the given componentB has high priority
+ * @return the {@code as Type} cast written on the initializer, or null
*/
- boolean compare(int componentA, int componentB);
+ String getCastType();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALExprCondition.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALExprCondition.java
index e3c3eedfc1..77d0788ebc 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALExprCondition.java
@@ -13,24 +13,15 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * A bare value expression used as a condition, true when it is present and not falsy.
+ */
+public interface TALExprCondition extends TALCondition {
+ TALValueAccess getExpr();
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+ String getCastType();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFieldSegment.java
similarity index 61%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFieldSegment.java
index e3c3eedfc1..d111e37be3 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFieldSegment.java
@@ -13,24 +13,18 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * A field access, {@code .name} or {@code ?.name}.
+ */
+public interface TALFieldSegment extends TALValueAccessSegment {
+ String getName();
/**
- * @return true if the given componentB has high priority
+ * @return whether the access was written with the safe-navigation operator
*/
- boolean compare(int componentA, int componentB);
+ boolean isSafeNav();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionArg.java
similarity index 61%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionArg.java
index e3c3eedfc1..e3a8183753 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionArg.java
@@ -13,24 +13,18 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- int getServerIdBasedOnComponent(int componentId);
-
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * One argument of a function or method call, with the cast the rule wrote on it.
+ */
+public interface TALFunctionArg {
+ TALValueAccess getValue();
/**
- * @return true if the given componentB has high priority
+ * @return the {@code as Type} cast written on this argument, or null
*/
- boolean compare(int componentA, int componentB);
+ String getCastType();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionCallConditionValue.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionCallConditionValue.java
index e3c3eedfc1..69f7e1a8ce 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALFunctionCallConditionValue.java
@@ -13,24 +13,17 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- int getServerIdBasedOnComponent(int componentId);
+import java.util.List;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
+/**
+ * A call to a DSL built-in on the right of a comparison, its arguments already reduced to literals by the parser.
+ */
+public interface TALFunctionCallConditionValue extends TALConditionValue {
+ String getFunctionName();
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+ List<String> getArguments();
}
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALIndexSegment.java
similarity index 60%
copy from oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
copy to oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALIndexSegment.java
index e3c3eedfc1..57e8168272 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/IComponentLibraryCatalogService.java
+++ b/oap-server/analyzer/trace-analyzer/src/main/java/org/apache/skywalking/oap/trace/analyzer/v2/compiler/model/TALIndexSegment.java
@@ -13,24 +13,13 @@
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
- *
*/
-package org.apache.skywalking.oap.server.core.config;
-
-import org.apache.skywalking.oap.server.library.module.Service;
-
-public interface IComponentLibraryCatalogService extends Service {
- int getComponentId(String componentName);
-
- int getServerIdBasedOnComponent(int componentId);
+package org.apache.skywalking.oap.trace.analyzer.v2.compiler.model;
- String getComponentName(int componentId);
-
- String getServerNameBasedOnComponent(int componentId);
-
- /**
- * @return true if the given componentB has high priority
- */
- boolean compare(int componentA, int componentB);
+/**
+ * A list index access, {@code [n]}.
+ */
+public interface TALIndexSegment extends TALValueAccessSegment {
... 11277 lines suppressed ...