Consolidate Tracer procedures #3442

rh-max · 2024-11-08T10:50:36Z

What changes are you introducing?

Consolidating two procedures on configuring Tracer, which have a lot of overlap.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

https://issues.redhat.com/browse/SAT-28625

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.13/Katello 4.15 (Satellite 6.17)
Foreman 3.12/Katello 4.14 (Satellite 6.16)
Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only)
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
Foreman 3.8/Katello 4.10
Foreman 3.7/Katello 4.9 (Satellite 6.14)
Foreman 3.6/Katello 4.8
Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions · 2024-11-08T10:52:24Z

The PR preview for eb4dfe1 is available at theforeman-foreman-documentation-preview-pr-3442.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

maximiliankolb · 2024-11-08T12:00:52Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

@@ -1,18 +1,31 @@
-[id="enabling-tracer-on-a-host_{context}"]
-= Enabling Tracer on a host
+[id="Configuring_Tracer_on_a_host_{context}"]


Suggested change

[id="Configuring_Tracer_on_a_host_{context}"]

[id="configuring-tracer-on-a-host"]

If we already change it, we could drop "context" too which we've not decided but done in the past regularly.

Very much option/not blocking your PR.

maximiliankolb · 2024-11-08T12:01:46Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc


-Use this procedure to enable Tracer on {Project} and access Traces.
-Tracer displays a list of services and applications that need to be restarted.
+You can install Tracer on {ProjectName} and access Traces.


Suggested change

You can install Tracer on {ProjectName} and access Traces.

You can install Tracer on hosts and access Traces on {Project}.

maximiliankolb · 2024-11-08T13:26:35Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

 . In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
 . Click the name of the host you want to modify.
 . On the *Traces* tab, click *Enable Traces*.
 . Select the provider to install `katello-host-tools-tracer` from the list.
+
+Alternatively, install Tracer using the CLI:


do we really want to document this?

If so, it'd probably just be the same commands as the template. Also, "yum" only works for EL7+.

We can, but then we should use the proper heading for a CLI procedure:

Suggested change

Alternatively, install Tracer using the CLI:

[id="cli-Configuring..."]

.CLI procedure

But with ".CLI procedure", we generally refer to Foreman/Smart Proxies, not commands on hosts. I like that there's abstraction for the commands on hosts through the REX job templates.

Lennonka · 2024-11-14T00:39:34Z

guides/common/assembly_administering-hosts.adoc

@@ -24,7 +24,10 @@ include::modules/proc_changing-the-environment-of-a-host.adoc[leveloffset=+1]

 include::modules/proc_changing-the-managed-status-of-a-host.adoc[leveloffset=+1]

-include::modules/proc_enabling-tracer-on-a-host.adoc[leveloffset=+1]
+:parent-context: {context}
+:context: administering-hosts


Is there any particular reason to change the context for this procedure?
Unless it's absolutely necessary to change the context, I would avoid it. Generally, it prevents problems with broken links in the web UI.

Lennonka · 2024-11-14T00:45:35Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

 . In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
 . Click the name of the host you want to modify.
 . On the *Traces* tab, click *Enable Traces*.
 . Select the provider to install `katello-host-tools-tracer` from the list.
+
+Alternatively, install Tracer using the CLI:


We can, but then we should use the proper heading for a CLI procedure:

Suggested change

Alternatively, install Tracer using the CLI:

[id="cli-Configuring..."]

.CLI procedure

Lennonka · 2024-11-14T00:45:56Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

 . Click *Enable Tracer*.
 You get a REX job notification after the remote execution job is complete.


This step looks like it doesn't belong to the CLI procedure. It should probably go above, together with the web UI procedure.

Lennonka · 2024-11-14T00:47:25Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

Nice to have would be to find out on what operating systems Tracer can be installed if there are any apart from RHEL and add this info to the introduction of the procedure.

maximiliankolb

I am currently working on the same issue in downstream docs ~~and will provide a patch/some insight on Tracer on different Client OS~~.

maximiliankolb · 2024-11-14T10:15:14Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

 . In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
 . Click the name of the host you want to modify.
 . On the *Traces* tab, click *Enable Traces*.
 . Select the provider to install `katello-host-tools-tracer` from the list.
+
+Alternatively, install Tracer using the CLI:


But with ".CLI procedure", we generally refer to Foreman/Smart Proxies, not commands on hosts. I like that there's abstraction for the commands on hosts through the REX job templates.

maximiliankolb · 2024-11-14T10:16:26Z

guides/common/modules/proc_configuring-tracer-on-a-host.adoc

 . Click *Enable Tracer*.
 You get a REX job notification after the remote execution job is complete.
+. Upload the Tracer data to the {ProjectName} server:


Suggested change

. Upload the Tracer data to the {ProjectName} server:

. Upload the Tracer data to your {ProjectServer}:

Consolidate Tracer procedures

2f440b7

pr-processor bot added the Not yet reviewed label Nov 8, 2024

rh-max added Needs tech review Requires a review from the technical perspective and removed Not yet reviewed labels Nov 8, 2024

Add a specific context for multiple module inclusion

eb4dfe1

maximiliankolb reviewed Nov 8, 2024

View reviewed changes

Lennonka requested changes Nov 14, 2024

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Nov 14, 2024

maximiliankolb reviewed Nov 14, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consolidate Tracer procedures #3442

Consolidate Tracer procedures #3442

rh-max commented Nov 8, 2024 •

edited

Loading

github-actions bot commented Nov 8, 2024 •

edited

Loading

maximiliankolb Nov 8, 2024

maximiliankolb Nov 8, 2024

maximiliankolb Nov 8, 2024

Lennonka Nov 14, 2024

maximiliankolb Nov 14, 2024

Lennonka Nov 14, 2024

Lennonka Nov 14, 2024

Lennonka Nov 14, 2024

Lennonka Nov 14, 2024

maximiliankolb left a comment •

edited

Loading

maximiliankolb Nov 14, 2024

maximiliankolb Nov 14, 2024

	[id="Configuring_Tracer_on_a_host_{context}"]
	[id="configuring-tracer-on-a-host"]

	You can install Tracer on {ProjectName} and access Traces.
	You can install Tracer on hosts and access Traces on {Project}.

	Alternatively, install Tracer using the CLI:
	[id="cli-Configuring..."]
	.CLI procedure

		. Click Enable Tracer.
		You get a REX job notification after the remote execution job is complete.

	. Upload the Tracer data to the {ProjectName} server:
	. Upload the Tracer data to your {ProjectServer}:

Consolidate Tracer procedures #3442

Are you sure you want to change the base?

Consolidate Tracer procedures #3442

Conversation

rh-max commented Nov 8, 2024 • edited Loading

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Checklists

github-actions bot commented Nov 8, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximiliankolb left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rh-max commented Nov 8, 2024 •

edited

Loading

github-actions bot commented Nov 8, 2024 •

edited

Loading

maximiliankolb left a comment •

edited

Loading