OTel working branch targeting OTel feature branch #4894

janan07 · 2026-01-20T10:25:51Z

Describe your pull request here: This is the working branch for dev use that targets the OTel feature branch

List the file(s) included in this PR:

After creating the PR, follow the instructions in the comments.

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions · 2026-01-20T10:26:04Z

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.

Add the label review: doc.
Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
- If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
Select the master branch if your PR updates content that is on the live site. Select docs-staging if your PR updates content for a future release.
Notify the Doc Squad about this PR. If you don't know whom should review your content, message the #zowe-doc Slack channel. If you know which Doc Squad writer should approve your content, add that person as a reviewer.

Need help? Contact the Doc Squad in the #zowe-doc Slack channel.

github-actions · 2026-01-20T10:26:06Z

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

github-actions · 2026-01-20T10:32:20Z

🚀 Deployed on https://697b360eccb64e0c7516c4b9--zowe-docs-master.netlify.app

Signed-off-by: Andrew Jandacek <[email protected]>

balhar-jakub

From the skeleton point of view, these are the only changes that would make the usage of the skeleton easier.

Let me know once the general explanation is available and I will review this part.

docs/user-guide/api-mediation/observability/observability-outline.md

Signed-off-by: Andrew Jandacek <[email protected]>

richard-salac · 2026-01-28T13:14:30Z

docs/user-guide/api-mediation/observability/configuring-otel-service-attributes.md

+Groups services into logical sets. Use this property value to distinguish between different installations, such as sysplex-a vs. sysplex-b, or north-datacenter vs. south-datacenter. `service.name` is expected to be unique within the same `namespace`.
+
+* **service.instance.id** (The Unique Instance)  
+Identifies the specific running process or Address Space. Must be unique for each instance of `service.name` and `service.namespace` pair. On z/OS, this property is typically mapped to the Job Name or a unique UUID.


Not true with jobname. Instance id must be globally unique. All instances on different lpars may have the same job name.

Is this better?

service.instance.id (The Unique Instance)
Identifies a specific running process or Address Space. This value must be globally unique for every instance. As multiple z/OS systems can run identical Job Names, ensure that you combine the Job Name with a unique identifier (such as the LPAR name or a UUID) to ensure the instance can be isolated during troubleshooting.

richard-salac · 2026-01-28T13:17:26Z

docs/user-guide/api-mediation/observability/configuring-otel-service-attributes.md

+        resource:
+          attributes:
+            service.name: "zowe-apiml"
+            service.namespace: "production-plex"


I suggest we put only examples of complete configuration instead of partial ones to specific attribute groups. For instance, here I would expect the 'production' to be set as deployment attribute

Are you suggesting then that we remove all configuration examples in this article or replace them with the complete configuration? If the latter, can you provide me with the complete configuration?

docs/user-guide/api-mediation/observability/configuring-otel-zos-attributes.md

richard-salac · 2026-01-28T13:34:40Z

docs/user-guide/api-mediation/observability/enabling-observability-in-zowe-yaml.md

+  * **resource.attributes**  
+    A collection of key-value pairs used to identify the telemetry source. See the following sub-properties of `resource.attributes`:
+
+    * **service.name**  


Here we duplicate the explanation of service attributes that we have in a separate md file just for them. Similarly for the deployment. It will be difficult to keep them in sync over time.

If you think it's sufficient, I can link to the specific attribute article for these three resources. It just seems that if we have an article for enablement, the user should have an easy reference to what parms are being configured...

docs/user-guide/api-mediation/observability/enabling-observability-in-zowe-yaml.md

Signed-off-by: Andrew Jandacek <[email protected]>

iansergeant42

Looking pretty good. Just a few things to address.

iansergeant42 · 2026-01-29T07:51:02Z

docs/user-guide/api-mediation/observability/configuring-otel-service-attributes.md

@@ -0,0 +1,96 @@
+# Configure OpenTelemetry Service Attributes
+
+Services are identified via the service.name, service.namespace, and service.instance.id properties. Together, these attributes create a unique identity for API ML instances across your enterprise.


service.name, service.namespace, and service.instance.id? Trying to be consistent...

iansergeant42 · 2026-01-29T07:56:25Z

docs/user-guide/api-mediation/observability/configuring-otel-zos-attributes.md

+
+## z/OS Attribute Reference
+
+The following attributes are captured during system discovery to describe the mainframe environment:


A couple of things:

Can we describe what 'system discovery' means here? What actually populates the attributes? Our junior sys prog won't understand it.

Given Richard's statement on process.pid not being configured by system discovery, does this move to another section?

iansergeant42 · 2026-01-29T07:58:10Z

docs/user-guide/api-mediation/observability/enabling-observability-in-zowe-yaml.md

+  * **exporter.otlp.protocol**  
+    The protocol is either `grpc` or `http/protobuf`.
+    **Default:** `grcp`


To note here that if we do reinstate, we have a typo with grpc and grcp mentioned.

iansergeant42 · 2026-01-29T07:59:02Z

docs/user-guide/api-mediation/observability/enabling-observability-in-zowe-yaml.md

+    exporter:
+      otlp:
+        endpoint: "http://otel-collector.your.domain:4317"
+        protocol: "grpc"


To be removed as per Richard above

iansergeant42 · 2026-01-29T08:00:57Z

docs/user-guide/api-mediation/observability/using-your-otel-metrics.md

@@ -0,0 +1,22 @@
+# Using Your API ML OpenTelemetry Metrics
+
+## Examples of Useability of Telemetry data in API ML


Typo. Usability.

Signed-off-by: Andrew Jandacek <[email protected]>

create skeleton of OTel

fa3bfce

Signed-off-by: Andrew Jandacek <[email protected]>

janan07 requested a review from richard-salac January 20, 2026 10:26

janan07 added area: apiml This issue is related to Zowe API Mediation Layer release: V3 Zowe V3 content review: sme Needs review by an SME labels Jan 20, 2026

janan07 requested review from balhar-jakub and iansergeant42 January 20, 2026 10:31

github-actions bot temporarily deployed to pull request January 20, 2026 10:32 Inactive

add titles

8b871cb

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 20, 2026 10:47 Inactive

janan07 added 2 commits January 20, 2026 16:53

add initial draft of intro

11e7bbd

Signed-off-by: Andrew Jandacek <[email protected]>

grammar fix

57ed363

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 20, 2026 16:05 Inactive

Add content for Resource Attributes and Enabling Observability

bd31f03

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 21, 2026 10:52 Inactive

add content to enable observability

01ca53b

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 21, 2026 13:20 Inactive

add considerations for config service attributes

c3ac1fb

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 22, 2026 09:53 Inactive

balhar-jakub reviewed Jan 22, 2026

View reviewed changes

docs/user-guide/api-mediation/observability/observability-outline.md Outdated Show resolved Hide resolved

docs/user-guide/api-mediation/observability/observability-outline.md Outdated Show resolved Hide resolved

add req service attribute list

6af333e

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 22, 2026 10:56 Inactive

add links to outline and reorder using section per Richard's feedback

fea7e6e

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 22, 2026 11:12 Inactive

add details

3915103

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 22, 2026 13:46 Inactive

initial draft of process and properties for acquiring z/OS Attributes

88763be

Signed-off-by: Andrew Jandacek <[email protected]>

add links to uis and fix formatting

4caee5c

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 27, 2026 14:31 Inactive

fix sidebar in using

daf14f1

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 27, 2026 15:22 Inactive

improve service attribute topic

bfed466

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 27, 2026 15:54 Inactive

janan07 added 2 commits January 27, 2026 17:03

improve zos attribute content

5f65bde

Signed-off-by: Andrew Jandacek <[email protected]>

updates to overview topic

21c6c52

Signed-off-by: Andrew Jandacek <[email protected]>

github-actions bot temporarily deployed to pull request January 27, 2026 16:22 Inactive

remove config-apiml-observability-via-opentelemetry.md file

3604057

Signed-off-by: Andrew Jandacek <[email protected]>

janan07 changed the base branch from docs-staging to janan07/otel-feature-branch January 28, 2026 10:50

janan07 changed the title ~~create skeleton of OTel~~ OTel working branch targeting OTel feature branch Jan 28, 2026