Skip to content

Rewrite observability page descriptions (next trees)#2709

Open
ctauchen wants to merge 1 commit intotigera:mainfrom
ctauchen:descriptions-observability
Open

Rewrite observability page descriptions (next trees)#2709
ctauchen wants to merge 1 commit intotigera:mainfrom
ctauchen:descriptions-observability

Conversation

@ctauchen
Copy link
Copy Markdown
Collaborator

@ctauchen ctauchen commented May 8, 2026

Summary

Refreshes the frontmatter description field on all 62 observability pages in the next (unversioned) trees:

  • calico/observability/ — 4 files (Whisker / Goldmane / basic flow visibility)
  • calico-enterprise/observability/ — 31 files
  • calico-cloud/observability/ — 27 files

Each rewritten description names its canonical product (Calico Open Source, Calico Enterprise, or Calico Cloud), stays within 200 characters, drops the forbidden verbs enable, disable, teaching, avoids YAML-breaking colons, and is unique across products.

CE and CC overlap heavily on this surface area, so descriptions disambiguate by deployment context: Calico Enterprise pages reference the in-cluster Manager UI and in-cluster Elasticsearch/Kibana; Calico Cloud pages reference the web console for connected clusters and managed Elasticsearch. Calico Open Source uses Whisker / Goldmane vocabulary instead.

This follows the same format and rules as #2696 (getting-started) and #2697 (network-policy).

Pre-fix violation summary

Inventory of the 62 existing descriptions before the rewrite:

Issue Count
Missing description 0
> 200 characters 0
Forbidden words (enable, disable, teaching) 5
Stray colon in value 0
Cross-product duplicates several (CE↔CC: alerts, dashboards, kibana, packetcapture, iptables, kube-audit, archive-storage, bgp, l7 datatypes, dns datatypes, flow datatypes, retention pages, etc.)

The pre-fix description: Enable ... lines were:

  • calico/observability/enable-whisker.mdx
  • calico-enterprise/observability/kube-audit.mdx
  • calico-cloud/observability/kube-audit.mdx
  • calico-enterprise/observability/elastic/flow/hep.mdx
  • calico-cloud/observability/elastic/flow/hep.mdx

Scope

Next (unversioned) trees only. Versioned mirrors under *_versioned_docs/ will be updated in a follow-up PR after review.

Reproducible verification

After the rewrite, all four content checks return zero:

# forbidden verbs
grep -nEri "^description:.*\b(enable|disable|teaching)\b" \
  calico/observability calico-enterprise/observability calico-cloud/observability

# length, uniqueness, and presence checks
python3 - <<'PY'
import os, re
from collections import Counter
descs = {}
for root in ['calico/observability','calico-enterprise/observability','calico-cloud/observability']:
    for dp, _, fs in os.walk(root):
        for f in sorted(fs):
            if f.endswith(('.mdx','.md')):
                p = os.path.join(dp, f); t = open(p).read()
                m = re.search(r'^description:[ \t]*(.*)$', t, re.MULTILINE)
                d = m.group(1).strip() if m else ''
                if d.startswith('"') and d.endswith('"'): d = d[1:-1]
                descs[p] = d
print('total', len(descs))
print('missing', sum(1 for d in descs.values() if not d))
print('over_200', sum(1 for d in descs.values() if len(d) > 200))
print('with_colon', sum(1 for d in descs.values() if ':' in d))
print('dupes', sum(1 for d, n in Counter(descs.values()).items() if n > 1))
PY

Vale was also re-run on the changed files; zero new line-2 (description-line) issues remain.

Test plan

  • CI Vale lint passes on the changed files
  • Spot-check that each rewritten description still matches its page's actual purpose
  • Confirm the next/unversioned scope (no versioned files touched)

@ctauchen
Rewrite observability page descriptions in next trees
9621550 
Refresh frontmatter description for all 62 observability pages across
calico/, calico-enterprise/, and calico-cloud/. Each page now names its
canonical product, fits within 200 characters, drops forbidden verbs
(enable/disable/teaching), and stays unique across products.

Disambiguates Calico Enterprise (in-cluster Manager UI, in-cluster
Elasticsearch and Kibana) from Calico Cloud (web console for connected
clusters, managed Elasticsearch). Calico Open Source uses the smaller
Whisker / Goldmane vocabulary.

Next trees only -- versioned mirrors will be applied after review.
Copilot AI review requested due to automatic review settings May 8, 2026 15:59
@ctauchen ctauchen requested a review from a team as a code owner May 8, 2026 15:59
@netlify
Copy link
Copy Markdown

netlify Bot commented May 8, 2026 •
edited
Loading

✅ Deploy Preview succeeded!

Built without sensitive environment variables

Name Link
🔨 Latest commit 9621550
🔍 Latest deploy log https://app.netlify.com/projects/tigera/deploys/69fe08500f47140008449bdd
😎 Deploy Preview https://deploy-preview-2709--tigera.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 98 (🟢 up 11 from production)
Accessibility: 98 (no change from production)
Best Practices: 83 (no change from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify
Copy link
Copy Markdown

netlify Bot commented May 8, 2026 •
edited
Loading

✅ Deploy Preview for calico-docs-preview-next ready!

Name Link
🔨 Latest commit 9621550
🔍 Latest deploy log https://app.netlify.com/projects/calico-docs-preview-next/deploys/69fe08503f54ac0008839744
😎 Deploy Preview https://deploy-preview-2709--calico-docs-preview-next.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI reviewed May 8, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR refreshes the frontmatter description field across the observability documentation in the unversioned (“next”) trees for Calico Open Source, Calico Enterprise, and Calico Cloud, aiming for clearer product-specific, unique, and policy-compliant descriptions.

Changes:

  • Rewrites description: frontmatter on 62 observability pages across calico/, calico-enterprise/, and calico-cloud/.
  • Standardizes descriptions to include the canonical product name and better distinguish CE vs CC contexts (self-managed/in-cluster vs connected clusters/managed services).
  • Removes previously forbidden “Enable …” phrasing on affected pages.

Reviewed changes

Copilot reviewed 62 out of 62 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
calico/observability/index.mdx Update observability landing-page frontmatter description (OSS).
calico/observability/view-flow-logs.mdx Update frontmatter description for Whisker flow log viewing (OSS).
calico/observability/enable-whisker.mdx Update frontmatter description for activating Goldmane/Whisker (OSS).
calico/observability/flow-logs-api.mdx Update frontmatter description for Goldmane API reference (OSS).
calico-enterprise/observability/index.mdx Update observability landing-page frontmatter description (CE).
calico-enterprise/observability/alerts.mdx Update frontmatter description for alerts management (CE).
calico-enterprise/observability/dashboards.mdx Update frontmatter description for dashboards (CE).
calico-enterprise/observability/get-started-cem.mdx Update frontmatter description for Manager UI tour (CE).
calico-enterprise/observability/visualize-traffic.mdx Update frontmatter description for Service Graph visualization (CE).
calico-enterprise/observability/packetcapture.mdx Update frontmatter description for packet capture (CE).
calico-enterprise/observability/kube-audit.mdx Update frontmatter description for Kubernetes API audit logging (CE).
calico-enterprise/observability/kibana.mdx Update frontmatter description for Kibana usage (CE).
calico-enterprise/observability/iptables.mdx Update frontmatter description for iptables log volume reference (CE).
calico-enterprise/observability/review-unused-network-policies.mdx Update frontmatter description for unused policy review workflow (CE).
calico-enterprise/observability/elastic/index.mdx Update frontmatter description for Elastic logs section index (CE).
calico-enterprise/observability/elastic/overview.mdx Update frontmatter description for Elastic stack overview (CE).
calico-enterprise/observability/elastic/troubleshoot.mdx Update frontmatter description for Elastic troubleshooting (CE).
calico-enterprise/observability/elastic/retention.mdx Update frontmatter description for retention configuration (CE).
calico-enterprise/observability/elastic/rbac-elasticsearch.mdx Update frontmatter description for Elasticsearch RBAC configuration (CE).
calico-enterprise/observability/elastic/archive-storage.mdx Update frontmatter description for log archival/forwarding (CE).
calico-enterprise/observability/elastic/audit-overview.mdx Update frontmatter description for audit logs overview (CE).
calico-enterprise/observability/elastic/bgp.mdx Update frontmatter description for BGP logs schema reference (CE).
calico-enterprise/observability/elastic/dns/index.mdx Update frontmatter description for DNS logs section index (CE).
calico-enterprise/observability/elastic/dns/dns-logs.mdx Update frontmatter description for DNS log fields/querying (CE).
calico-enterprise/observability/elastic/dns/filtering-dns.mdx Update frontmatter description for DNS log filtering (CE).
calico-enterprise/observability/elastic/flow/index.mdx Update frontmatter description for flow logs section index (CE).
calico-enterprise/observability/elastic/flow/aggregation.mdx Update frontmatter description for flow log aggregation tuning (CE).
calico-enterprise/observability/elastic/flow/datatypes.mdx Update frontmatter description for flow log fields reference (CE).
calico-enterprise/observability/elastic/flow/filtering.mdx Update frontmatter description for flow log filtering (CE).
calico-enterprise/observability/elastic/flow/hep.mdx Update frontmatter description for HostEndpoint reporting (CE).
calico-enterprise/observability/elastic/flow/processpath.mdx Update frontmatter description for process-path enrichment (CE).
calico-enterprise/observability/elastic/flow/tcpstats.mdx Update frontmatter description for TCP socket stats enrichment (CE).
calico-enterprise/observability/elastic/l7/index.mdx Update frontmatter description for L7 logs section index (CE).
calico-enterprise/observability/elastic/l7/configure.mdx Update frontmatter description for L7 log configuration (CE).
calico-enterprise/observability/elastic/l7/datatypes.mdx Update frontmatter description for L7 log fields reference (CE).
calico-cloud/observability/index.mdx Update observability landing-page frontmatter description (CC).
calico-cloud/observability/alerts.mdx Update frontmatter description for alerts management (CC).
calico-cloud/observability/dashboards.mdx Update frontmatter description for dashboards (CC).
calico-cloud/observability/create-custom-dashboard.mdx Update frontmatter description for custom dashboard creation (CC).
calico-cloud/observability/visualize-traffic.mdx Update frontmatter description for external-traffic visualization (CC).
calico-cloud/observability/packetcapture.mdx Update frontmatter description for packet capture (CC).
calico-cloud/observability/kube-audit.mdx Update frontmatter description for Kubernetes API audit logging (CC).
calico-cloud/observability/kibana.mdx Update frontmatter description for Kibana usage (CC).
calico-cloud/observability/iptables.mdx Update frontmatter description for iptables log volume reference (CC).
calico-cloud/observability/elastic/index.mdx Update frontmatter description for Elastic logs section index (CC).
calico-cloud/observability/elastic/overview.mdx Update frontmatter description for Elastic stack overview (CC).
calico-cloud/observability/elastic/archive-storage.mdx Update frontmatter description for log archival/forwarding (CC).
calico-cloud/observability/elastic/audit-overview.mdx Update frontmatter description for audit logs overview (CC).
calico-cloud/observability/elastic/bgp.mdx Update frontmatter description for BGP logs schema reference (CC).
calico-cloud/observability/elastic/dns/index.mdx Update frontmatter description for DNS logs section index (CC).
calico-cloud/observability/elastic/dns/dns-logs.mdx Update frontmatter description for DNS log fields/querying (CC).
calico-cloud/observability/elastic/dns/filtering-dns.mdx Update frontmatter description for DNS log filtering (CC).
calico-cloud/observability/elastic/flow/index.mdx Update frontmatter description for flow logs section index (CC).
calico-cloud/observability/elastic/flow/aggregation.mdx Update frontmatter description for flow log aggregation tuning (CC).
calico-cloud/observability/elastic/flow/datatypes.mdx Update frontmatter description for flow log fields reference (CC).
calico-cloud/observability/elastic/flow/filtering.mdx Update frontmatter description for flow log filtering (CC).
calico-cloud/observability/elastic/flow/hep.mdx Update frontmatter description for HostEndpoint reporting (CC).
calico-cloud/observability/elastic/flow/processpath.mdx Update frontmatter description for process-path enrichment (CC).
calico-cloud/observability/elastic/flow/tcpstats.mdx Update frontmatter description for TCP socket stats enrichment (CC).
calico-cloud/observability/elastic/l7/index.mdx Update frontmatter description for L7 logs section index (CC).
calico-cloud/observability/elastic/l7/configure.mdx Update frontmatter description for L7 log configuration (CC).
calico-cloud/observability/elastic/l7/datatypes.mdx Update frontmatter description for L7 log fields reference (CC).

Comment thread calico-enterprise/observability/dashboards.mdx
@@ -1,5 +1,5 @@
---
description: Dashboards help you see what's going on in your cluster. See how your cluster is performing and visualize your system's log data.
description: Visualize cluster activity in the Calico Enterprise Manager UI with prebuilt dashboards for cluster health, policy, DNS, and L7 log data.
Comment thread calico-cloud/observability/dashboards.mdx
@@ -1,5 +1,5 @@
---
description: Dashboards help you see what's going on in your cluster. See how your cluster is performing and visualize your system's log data.
description: Visualize connected cluster activity in the Calico Cloud web console with prebuilt and custom dashboards for cluster health, policy, DNS, and L7 data.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ctauchen