Adds stub MDX pages for the new Datadog Integration guide in each locale,
with translated frontmatter and a "translation in progress" note. Body
content is English while waiting on full translations, matching the
discoverability of every other Enterprise guide.
Also reframes capture_telemetry_logs.mdx in each locale to match the en
restructure: a translated lead Tip recommending OpenTelemetry as the
vendor-neutral default, and a slimmed-down Datadog tab that points at
the dedicated Datadog Integration guide instead of duplicating its
collector configuration steps.
Registers the new datadog page in the pt-BR/ko/ar edge sidebars where
the old datadog_dashboard entry would have lived. structured_logs is
intentionally not re-stubbed — the schema lives inside the Datadog page
now.
Co-authored-by: Cursor <cursoragent@cursor.com>
Merges the standalone structured_logs guide into a dedicated Datadog
Integration page. The stdout JSON schema is Datadog-Agent-path-specific
in practice (OTLP path uses OpenTelemetry attribute names), so a
vendor-neutral structured-logs page was misleading. Now Datadog customers
have one canonical page covering both ingestion paths plus the dashboard
import, and non-Datadog customers land on the OpenTelemetry Export page
without being buried in Datadog content.
- Delete docs/edge/en/enterprise/guides/structured_logs.mdx; the schema
reference moves verbatim into the new datadog.mdx as an anchor-linkable
section.
- Rename datadog_dashboard.mdx to datadog.mdx (preserved via git mv).
New structure: choose-a-path tabs (Datadog Agent recommended /
Datadog OTLP intake) → log schema reference (with explicit Info
callout that it's the Agent-path schema, not OTLP) → dashboard
import → verify ingestion → customize → troubleshooting.
- Move the Datadog OTLP UI walkthrough (site domain, API key,
/v1/traces vs /v1/logs paths) onto the Datadog page so it lives in
exactly one place. Datadog dashboard JSON artifact path stays at
datadog_dashboard.json — the file name is artifact-specific.
- Reframe capture_telemetry_logs.mdx: add a lead Tip recommending OTel
as the vendor-neutral first option, and shrink the Datadog tab to a
pointer to the new Datadog Integration guide.
- Update docs/docs.json en edge sidebar: drop structured_logs, replace
datadog_dashboard with datadog.
Co-authored-by: Cursor <cursoragent@cursor.com>
Adds stub MDX pages with translated frontmatter and a "translation in
progress" note in each locale. Body content is English while waiting on
full translations, matching the discoverability of every other Enterprise
guide (registered across all four edge locales).
Also translates the Datadog OTLP /v1/logs touch-up and the new cross-links
in pt-BR/ko/ar versions of capture_telemetry_logs.mdx.
Co-authored-by: Cursor <cursoragent@cursor.com>
Documents the structured-logs work shipped in crewAI-enterprise
PR #1195 and ships the customer-facing Datadog dashboard the CON-249
self-hosted observability ask called out for.
- docs/edge/en/enterprise/guides/structured_logs.mdx: schema v1
reference, opt-in env var (CREWAI_LOG_FORMAT=json), before/after
JSON example, compatibility contract. Backend-agnostic — usable
for Splunk, Loki, ELK, CloudWatch as well.
- docs/edge/en/enterprise/guides/datadog_dashboard.mdx: two ingestion
paths (Datadog Agent stdout vs Datadog OTLP intake) for self-hosted
customers to pick from, facet-promotion prerequisites, 3-step
dashboard import, dashboard tour, customization tips, troubleshooting.
- docs/edge/en/enterprise/guides/datadog_dashboard.json: the importable
dashboard artifact itself — 4 sections (Header / Throughput / Errors /
Cost) with template variables wired to @automation_name,
@crewai_version, and service.
- docs/edge/en/enterprise/guides/capture_telemetry_logs.mdx: clarify
that the default Datadog OTel template ships traces only and link to
the new log-export options (Structured Logs + Datadog Dashboard).
- docs/docs.json: register both new pages in the edge/en sidebar
alongside capture_telemetry_logs. Version snapshots (v1.x.x) and
non-English locales deliberately untouched — new content lives only
on the edge channel; translation stubs land in a follow-up PR.
Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.
Layout:
- docs/edge/<lang>/* rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/ shared, append-only
- docs/docs.json nav + redirects
URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.
Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
snapshot, inserts the version into every language block in
docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
Phase 2 of devtools release. Edge changelogs are updated first (so
the snapshot freeze picks them up), then the snapshot is staged
alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
— the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
and never accidentally touch a frozen snapshot.
Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
historical snapshots (v1.10.0 .. v1.14.7) from git tags via
git archive | tar, rewriting openapi: MDX refs so each snapshot
reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
rewrites every page path in 16 versioned blocks to point under
docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
v1.14.7 as Latest (default), prunes pages whose target file
doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
around docs_versioning.freeze for manual one-off freezes (e.g.
retroactively snapshotting a forgotten release).
CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
title contains [docs-freeze] (i.e. release-cut PRs generated by
devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
single image directory. Deleting or renaming an image breaks every
historical snapshot that still references it.
Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.
Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
copy, openapi rewrite, version insertion, default demotion, redirect
upserts, per-section redirect rewriting, idempotency, and invalid
inputs.
Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).
AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.
Co-authored-by: Cursor <cursoragent@cursor.com>
* style: resolve linter issues
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
