[PR] Point the APISIX guide at the deployed rules file and document the service.name trap [skywalking]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng opened a new pull request, #13978:
URL: https://github.com/apache/skywalking/pull/13978

   ### Fix two gaps left in the APISIX monitoring guide after #13976
   
   - [x] Add a unit test to verify that the fix works. (Not applicable — documentation only. Every claim was verified against the source; see below.)
   - [x] Explain briefly why the bug exists and how to fix it.
   
   #### 1. Customization pointed at the source tree, not the deployed file
   
   #13976 replaced `` `/config/otel-rules/apisix.yaml` `` with a repo-relative link into `oap-server/server-starter/src/main/resources/`. An operator customizing an installation edits the deployed copy — `apm-dist/src/main/assembly/binary.xml` packages `otel-rules/**` into `config/` — and every other monitoring guide that names its rules file uses the deployed path (`vm.yaml`, `windows.yaml`, the three `nginx-*.yaml`). No doc links into the source tree.
   
   The deployed path is named first, with the source link kept alongside for contributors.
   
   #### 2. The `service.name` trap was undocumented
   
   Nothing explained why a custom `skywalking_service` label exists when OpenTelemetry already has a standard attribute for service identity. The reason is that the standard one is already taken:
   
   - the Collector's Prometheus receiver converts the Prometheus `job` label into the `service.name` resource attribute;
   - `OpenTelemetryMetricRequestProcessor` maps `service.name` back to `job_name` (`FALLBACK_LABEL_MAPPINGS`, line 103);
   - the APISIX MAL rule filters on exactly that label — `filter: "{ tags -> tags.job_name == 'apisix-monitoring' }"` (`apisix.yaml:31`).
   
   So setting `service.name` to name an APISIX service changes the **filter key** rather than the service name. The rule stops matching and no APISIX metrics are produced — silently, with nothing in the docs to explain it. Reaching for the OTel-idiomatic attribute is the obvious move, which makes this worth stating explicitly.
   
   #### Also
   
   One line recording that each metric name in the table is the rule's `metricPrefix` (`meter_apisix`) joined to its entry's `name`, so a reader who opens `apisix.yaml` can connect `sv_http_requests` to `meter_apisix_sv_http_requests`.
   
   #### Verification
   
   - `apm-dist/src/main/assembly/binary.xml:71` includes `otel-rules/**`, confirming the deployed `config/otel-rules/` path
   - `OpenTelemetryMetricRequestProcessor.java:103` — `.put("service.name", "job_name")`
   - `otel-rules/apisix.yaml:31` — the `job_name` filter; `:34` — `metricPrefix: meter_apisix`
   - the relative link to the source file resolves
   - `license-eye header check` → 0 invalid across 4998 files
   
   - [x] If this pull request closes/resolves/fixes an existing issue, replace the issue number. (Not applicable.)
   - [x] Update the [`CHANGES` log](https://github.com/apache/skywalking/blob/master/docs/en/changes/changes.md).


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org