[brmur]

Problem

HITL style remediation (Task 3.9) flagged AWSDevDocsStyleGuide rule violations on 9 generated CloudWatch OpenTelemetry SDK example pages. Those pages are generated SDK code-example content injected into the AWSCloudWatch guide via AWSDocsSdkExamplesPublic; they are not editable in the AWSCloudWatch doc package, so the fixes must be made here in the generating source.

Tracking: P536241864 · Reference (Task 3.9): https://taskei.amazon.dev/tasks/D548933874

Changes applied

All changes are in the OTelMetrics scenario and its OTLP collector config, which is where the genuinely actionable prose lives.

Code	Rule	Fix
112095	Write around language-specific terms (action/method)	Reworded the Java, .NET, and Ruby excerpt descriptions in cloudwatch_Scenario_OTelMetrics to use "operations" / "wrapper code" instead of "SDK methods" / "OpenTelemetry actions" / "Define methods".
38043	Avoid loopback addresses	Reworded the collector-config comment from http://localhost:4318 to "the collector's OTLP HTTP endpoint on port 4318". (Note: substituting 127.0.0.1 would be worse; the address refers to the collector's own listening endpoint, so rewording is the correct fix.)
30051	Include version compatibility information	Added the minimum OpenTelemetry Collector release — 0.47.0, which first shipped sigv4authextension (verified via aws-observability/aws-otel-collector#1065) — to the collector-config prerequisites.

Validated with writeme.py --services cloudwatch --check: cloudwatch_metadata.yaml validation success, no CloudWatch errors; both edited YAML files parse.

Codes verified as false positives / not applicable

Tracing each remaining flagged code to source showed the flag targets a code identifier, an API property name, a concrete default value, or text that already complies / is not on these pages. Changing these would break code or introduce inconsistent churn, so they are intentionally not changed:

Code	Rule	Why not changed
36014	"time zone" as two words	Every timezone occurrence is the CloudWatch API property Timezone, a parameter/variable name, or a test value ("America/Los_Angeles"). The prose doc-comments already say "time zone". Renaming identifiers would break the examples.
68085	Avoid Latinisms (etc./e.g./i.e.)	No Latinisms appear on the 9 flagged pages. The only e.g. matches are in CloudWatchActions.java (the basics scenario), which does not render on these pages.
30065	Version constraints in dependency examples	These pages have no package-manifest-style dependency block. The collector is pinned by instruction (otelcol-contrib) and now carries an explicit minimum version (see 30051). There is no dependency list to annotate.
112125	Clear placeholder names	Replaceable values already use {region} / <region>. us-east-1 appears as a concrete working default, not as a placeholder named us-east-1 (the rule's negative example targets placeholders like bucket123 / func).
40038	Steps as complete independent sentences	The flagged C++ excerpt lead-ins ("Describe the contributors to a PromQL alarm.", "List the alarm mute rules.") are already complete imperative sentences in the repo-wide house style shared by thousands of excerpt descriptions. Rewording only these would make them inconsistent with the rest of the repo.

Testing

• writeme.py --services cloudwatch --check → cloudwatch_metadata.yaml validation success, no CloudWatch errors.
• Both edited YAML files confirmed well-formed.
• (An unrelated bedrock Kotlin missing-snippet error appears only on local /local/... checkouts and is tracked separately in Match .gitignore specs relative to walk root in walk_with_gitignore aws-doc-sdk-examples-tools#210; it does not affect CloudWatch or CI.)

[github-actions]

🤖 AI Code Example Review

This PR makes targeted prose/documentation fixes to address style guide violations in YAML metadata and a YAML config comment file. The changes are minimal, well-justified, and do not touch executable code. All modifications are appropriate and correct.

Detailed Review

1. [nit] .doc_gen/metadata/cloudwatch_metadata.yaml line 1875: The change from 'A wrapper class for the &CW; OpenTelemetry SDK methods.' to '...SDK operations.' is a clean, minimal fix that correctly avoids language-specific terminology. Good.

2. [nit] .doc_gen/metadata/cloudwatch_metadata.yaml line 1885: The change from 'Wrapper methods for the &CW; OpenTelemetry actions.' to 'Wrapper code for the &CW; OpenTelemetry operations.' is appropriate. 'Wrapper code' is slightly more generic than 'wrapper methods' and avoids the language-specific term, consistent with the style guide intent.

3. [nit] .doc_gen/metadata/cloudwatch_metadata.yaml line 1903: The change from 'Define methods that call...' to 'Define wrapper code that calls...' is consistent with the other two Ruby/Java/.NET fixes and avoids the flagged term. The grammar is correct.

4. [nit] python/example_code/cloudwatch/otlp_collector_config.yaml lines 24-25: Adding 'version 0.47.0 or later' is a meaningful improvement for users trying to use this config. The PR description provides a credible source (aws-observability/aws-otel-collector#1065). However, the version claim cannot be independently verified from the diff alone — reviewers should confirm this version number is accurate before merging.

5. [nit] python/example_code/cloudwatch/otlp_collector_config.yaml lines 36-37: Replacing 'http://localhost:4318' with 'the collector's OTLP HTTP endpoint on port 4318' is the correct approach for the style guide violation. Using 127.0.0.1 would be worse (same rule) and the address is a collector-side listener, not a user-facing URL, so rewording is more appropriate than substitution.

6. [policy] No test files are modified or added in this PR. Since these are exclusively prose/comment changes to YAML files (not executable code), the absence of new tests is expected and appropriate. The PR author notes writeme.py --services cloudwatch --check passes, which is the correct validation tool for this type of change.

7. [nit] The PR description is unusually thorough in documenting why certain flagged codes were intentionally not addressed (false positives table). This is good practice and aids reviewers, though it is not part of the code itself.

8. [nit] The three metadata description changes are internally consistent in style ('wrapper code' / 'operations'), which is good. Consider whether 'wrapper code' is the established term used elsewhere in the metadata file for consistency across all language entries — but this is a very minor point and the existing entries for other languages are not visible in the diff.

---

_{Reviewed at commit 175193f8433c37494fb843233c0cd0406718cb34. This review was generated automatically using Amazon Bedrock. It compares your changes against existing examples and coding guidelines. Findings are labeled by severity (blocking / nit / policy) and reflect only the commit above. Please use your judgment — this is advisory, not authoritative.}

[github-actions]

🤖 AI Code Example Review

This follow-up commit fully addresses all previously raised concerns. The two nit items from the prior review (version number specificity and loopback address rewording) are resolved, and no new issues are introduced. The PR remains a clean, minimal prose/documentation fix with no executable code changes.

Detailed Review

1. [nit] .doc_gen/metadata/cloudwatch_metadata.yaml lines 1875, 1885, 1903: All three description rewrites from the previous review are present and unchanged. The 'SDK methods' → 'SDK operations', 'Wrapper methods' → 'Wrapper code', and 'Define methods' → 'Define wrapper code' substitutions are internally consistent and correct.

2. [nit] python/example_code/cloudwatch/otlp_collector_config.yaml line 24: The prior nit about the minimum version '0.47.0' being an unverified factual claim was acknowledged in the PR description (citing aws-observability/aws-otel-collector#1065). The version is now present in the current code and the PR author has provided a source. This is as addressed as it can be in a prose-only PR; no further action is needed unless a reviewer independently disputes the version.

3. [nit] python/example_code/cloudwatch/otlp_collector_config.yaml line 37: The prior nit about the rewording removing useful port/protocol context was raised. The current code reads 'the collector's OTLP HTTP endpoint on port 4318', which preserves both the protocol (OTLP HTTP) and port (4318) while eliminating the loopback address. This is a good resolution — better than the prior version and better than the suggested alternative of using a generic placeholder.

4. [policy] No test files are modified or added. This is appropriate and expected for a prose-only YAML documentation change. The PR author confirms writeme.py --services cloudwatch --check passes, which is the correct validation mechanism for this type of change.

5. [nit] The PR description's false-positives table is thorough and well-reasoned. Each excluded code is justified with a concrete reason (API property name, identifier, concrete default value, etc.). This is good practice and aids reviewers.

6. [nit] All changes are minimal and targeted — only the lines that needed fixing were touched. There is no unrelated churn or reformatting, which is correct practice for a style-remediation PR.

7. [nit] The three metadata description changes are internally consistent across Java, .NET, and Ruby entries ('wrapper code' / 'operations'). This is a minor improvement over the previous state where each language had slightly different phrasing.

---

_{Reviewed at commit c46922bb192cbd8b30040d678986c43b67f052be. This review was generated automatically using Amazon Bedrock. It compares your changes against existing examples and coding guidelines. Findings are labeled by severity (blocking / nit / policy) and reflect only the commit above. Please use your judgment — this is advisory, not authoritative.}