OTel working branch targeting OTel feature branch

[janan07]

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.

[github-actions]

😺 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]

📁 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]

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

[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.

[richard-salac]

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

[janan07]

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]

Unfortunately it is not. The general truth is "This value must be globally unique for every instance." - that's valid.

"Identifies a specific running process or Address Space." - Neither of them can be used as instance identifier. When apiml is restarted, new process id as well as address space id is created, so it creates a unique identification of every execution instead of 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." - I am not sure this will work with 2 apiml instances installed on the same lpar.

I am more inclined to just describe the meaning at this point. We may update it with the first story finished.

[janan07]

Does this rewritten definition make more sense?

service.instance.id (The Unique Instance)
A stable, unique identifier for a single instance of the service. Unlike a Process ID (PID) or Address Space ID (ASID)—which change every time a service restarts—this ID should remain constant across the lifecycle of the deployment.

To ensure global uniqueness across your enterprise:
Single Instance per LPAR: Use a combination of the System Name and the Job Name (e.g., SYS1-ZOWEAPIML).

Multiple Instances per LPAR: If you run multiple API ML instances on the same z/OS system, you must include a unique suffix or port number (e.g., SYS1-ZOWEAPIML-7443 and SYS1-ZOWEAPIML-8443) to ensure they are differentiated in your monitoring tools.

[richard-salac]

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

[janan07]

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?

[richard-salac]

If we provide only the partial samples, can we be sure that the users will be able to navigate the docs to follow the right full sample? The use-case from the sysprog's perspective is to enable observability, not configure just some subset of attributes. They need to do it either all or nothing.

We do not have the configuration yet ad the implementation is still in progress.

[janan07]

That's fine, we can remove all of the examples and have a sample when the implementation is completed.

[richard-salac]

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.

[janan07]

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...

[richard-salac]

You are right, but we do not have specific list now as some of the attributes are discovered automatically. The purpose of this PR is to create a skeleton to be updated once we get the issues implemented.

[janan07]

Correct. This content is as a place-holder. I understand this could all change with the implementation.

[iansergeant42]

Looking pretty good. Just a few things to address.

[iansergeant42]

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

[iansergeant42]

A couple of things:

1. Can we describe what 'system discovery' means here? What actually populates the attributes? Our junior sys prog won't understand it.
2. Given Richard's statement on process.pid not being configured by system discovery, does this move to another section?

[iansergeant42]

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