Repository navigation
Remove deprecated site pages and deprecate docs superseded by CloudWatch OpenTelemetry guidance - #862
Merged
Merged
Conversation
- Delete the /videos page, its sections, and styles - Remove Videos link from the Community header dropdown - Remove Roadmap link from the About header dropdown and footer
- Delete the /about page, its sections, styles, and YAML content - Remove the About dropdown from the header and the About column from the footer
- Delete the /announcements page, AnnouncementWidget, styles, and announcements.yaml - Remove Latest Announcements from the homepage What's New section - Remove Announcements link from the header and its Gatsby source/search config
- Delete the /search page, Search component, and styles - Remove the Search button from the header - Remove the elasticlunr search plugin config and dependency
- Delete the partner docs pages (Datadog, Dynatrace, Logz.io, Splunk) - Remove the Partners section from the docs sidebar
- Delete the /get-involved page, its styles, and get-involved.yaml - Remove Get Involved links from the header Community dropdown and footer - Remove the Join button from the homepage Get Involved section
- Delete the /contributors page, styles, YAML, and the GitHub contributors build plugin - Delete the /resources page, styles, and YAML - Remove Contributors and Resources links from the header and footer - Drop the now-unused github-base and camelcase-keys dependencies
- Delete the /contributing and /code-of-conduct pages (the repo's CODE_OF_CONDUCT.md and CONTRIBUTING.md already cover these) - Replace the Community header dropdown with a top-level Blog link - Move Blog Posts and FAQ into the footer Discover column
Drop footer columns that duplicate the header (Documentation, GitHub, Download, Blog) and the duplicate Report a Bug/File an Issue links; keep FAQ, Report an Issue, and Twitter, and update the copyright year.
Remove the Benefits, Use Cases, and Open Source panels, which are superseded by OpenTelemetry support in Amazon CloudWatch. Rewrite the introduction to position ADOT alongside CloudWatch OTLP ingestion and Application Signals, and link to the CloudWatch OpenTelemetry docs.
The collector-centric diagram conflicts with current CloudWatch OpenTelemetry guidance.
Out of the box, the ADOT Collector exports with awsemf/awsxray and the ADOT SDKs export OTLP to a local collector, so the introduction should not imply ADOT sends data to the CloudWatch OTLP endpoints by default. Keep the introduction factual and add a callout with current AWS guidance.
wisemanIV
force-pushed
the
deprecate-legacy-docs
branch
from
October 18, 2026 17:54
26e1195 to
8f86ccf
Compare
…kends in homepage intro
wisemanIV
force-pushed
the
deprecate-legacy-docs
branch
from
October 18, 2026 17:57
93610f7 to
b2dc716
Compare
Replace 48 pages with deprecation notices that keep their URLs and link to the current AWS or upstream documentation, remove them from the docs sidebar, and delete the docker-compose sample page.
- Point readers to CloudWatch OTLP endpoints, the CloudWatch agent, Application Signals, and the CloudWatch Observability EKS add-on where pages present awsemf/awsxray or the ADOT Collector as the only path - Mark the ECS and EC2 collector tutorials as legacy - Remove an internal AMP gamma endpoint and fix the remote write path - Remove claims that the X-Ray ID generator or ADOT Collector is required - Fix broken links, anchors, and code samples (remote sampling YAML, Android manifest, Swift module name, add-on configuration keys)
Verified against the live add-on configuration schema (aws eks describe-addon-configuration): configuration keys use `resources`, and all operator and collector examples validate. Update version examples and the Kubernetes requirement to match the current default add-on version (Kubernetes 1.31-1.37).
Use the ADOT test Prometheus sample app (public.ecr.aws/aws-otel-test/prometheus-sample-app) instead of an image in a personal registry, listening on port 3000 to match the existing scrape annotations.
The tutorial deploys an AWS X-Ray SDK sample app; the X-Ray SDKs and daemon are in maintenance mode in favor of OpenTelemetry. Replace the setup/ecs hub and its 18 sub-pages with deprecation notices pointing to Application Signals on ECS, the X-Ray migration guide's ECS task definitions, and ECS Container Insights; remove it from the sidebar and retarget inbound links. Delete 103 images no longer referenced.
wisemanIV
force-pushed
the
deprecate-legacy-docs
branch
from
October 18, 2026 17:58
b2dc716 to
e4f71ce
Compare
- EKS add-on installation: add EKS Pod Identity / IRSA guidance with the add-on's service accounts and recommended policies, and link custom collector configuration (from aws-otel#771; verified against the add-on schema) - Python auto-instrumentation: require Python 3.10-3.14, matching ADOT Python v0.21.0 (from aws-otel#836, aws-otel#838) - X-Ray: fix sql.sanitized_query typo (from aws-otel#804) - Workflows: scope down GITHUB_TOKEN permissions (from aws-otel#800) - EKS add-on AMP config: note on escaping $ in Prometheus configs and fix prometheusremotewrite typo (from aws-otel#552) - Remote sampling: add the upstream JavaScript X-Ray sampler, now published (from aws-otel#542)
- Update the Java layer ARNs to v2.32.0 (AWSOpenTelemetryDistroJava:19 in most Regions) from the release notes. - Align the supported runtimes table with the runtimes the layers declare and Lambda supports: add Python 3.14, Node.js 24, Java 25, and .NET 10, remove the deprecated Node.js 18 and 20, and add an architectures column (.NET is x86_64 only). - Note that Java instrumentation requires a RequestHandler or RequestStreamHandler handler, and that Go, Rust, Ruby, and other provided.al2023 functions have no Application Signals layer. - Rewrite the Go guide for provided.al2023: OpenTelemetry Go SDK with otellambda, and the ADOT Collector Lambda layer configured to send traces to the X-Ray OTLP endpoint with SigV4.
The WarningBox, TipBox, and InfoBox buttons render their hyperlink as a plain anchor, so internal links such as /docs/setup/ecs skipped the Gatsby path prefix and broke when the site is built with --prefix-paths. Pass internal links through withPrefix. Without a path prefix the links are unchanged.
AWS App Runner stopped accepting new customers on April 30, 2026, and AWS recommends Amazon ECS Express Mode for new containerized applications. Remove the App Runner getting-started page and App Runner from the platforms on the introduction page. The v0.47.0 release notes keep their App Runner entry as a record of that release.
Traces sent over OTLP are stored and searched in CloudWatch with Transaction Search and Application Signals. Describe CloudWatch as the destination for traces instead of listing AWS X-Ray as a separate service, and refer to https://xray.<region>.amazonaws.com/v1/traces as the CloudWatch OTLP traces endpoint. Keep X-Ray where it names a feature or component: the awsxray exporter and receiver, X-Ray sampling rules and remote sampling, the X-Ray propagator, the X-Ray SDK, and console labels. Remove the duplicate X-Ray Exporter entry from the sidebar; the page remains under Getting started.
… syntax
Replace the awsxray and awsemf exporters in the embedded URI example with
otlp_http exporters that send traces and metrics to the CloudWatch OTLP
endpoints with sigv4auth, and drop the awsxray receiver.
The example put each embedded URI on its own line under the key, which
is not valid YAML: the collector fails with "retrieved value
(type=string) cannot be used as a Conf". Put the URI on the key's line
(receivers: ${s3://...}) and remove the indentation from the embedded
files. Tested on ADOT Collector v0.50.0 with the S3 URIs replaced by
file URIs.
The diagram showed AWS X-Ray as a source and destination and featured StatsD, Jaeger, Zipkin, and Kafka, which no longer reflect the guidance on the page. Remove it, and correct the Amazon OpenSearch Service name.
Describe https://xray.<region>.amazonaws.com/v1/traces as the CloudWatch OTLP traces endpoint rather than presenting AWS X-Ray as a separate destination.
Bring in the Lambda layer version and runtime updates and the rewritten Go guide from aws-otel#863, so that the documentation changes ship in one pull request. The Go guide replaces this branch's earlier edits to the old Go page.
Replace the awsxray exporter with an otlp_http exporter and sigv4auth extension that send sampled traces to the CloudWatch OTLP traces endpoint. Fix the path policy example, whose "\/users" value is not valid YAML for the collector, and use the current url.path attribute. Tested on ADOT Collector v0.50.0.
The diagram showed the AWS X-Ray and CloudWatch EMF exporters as the trace and metric paths. Keep the list of pipelines that the configuration guides cover, and the Operator flow diagram.
Replace the page with a deprecation notice that points to the CloudWatch OTLP traces endpoint, remove its sidebar entry, and delete its diagram.
Lambda is a compute platform like ECS, EC2, and EKS. The entry links to the existing Lambda page, so its URL doesn't change.
Replace the custom AWSDistroOpenTelemetryPolicy with the CloudWatchAgentServerPolicy managed policy, and merge the create and attach steps into one section.
Replace the awsemf exporter with otlp_http and sigv4auth, scope the task role to cloudwatch:PutMetricData and the discovery permissions, move ssm:GetParameters to the execution role, fix the invalid policy JSON, replace the EMF log and dashboard views with PromQL, and update the collector image. Also point the PromQL links to the CloudWatch PromQL overview.
Also describe the exporter without naming it, and link to PromQL querying for metrics sent to the OTLP endpoint.
…LP metrics endpoint Replace the awsemf exporter with otlp_http and sigv4auth in every example, query the metrics with PromQL, drop the EMF-only resource renaming, dimension limits, and built-in Container Insights config note, and use the non-deprecated metricstransform include key. All five configurations validate with ADOT Collector v0.50.0.
…ions Describe the EKS add-on's emf pipeline without the EMF name and point to an OTLP alternative, since the add-on schema (v0.158.0-eksbuild.1) only offers amp and emf pipelines. Link the OTLP/HTTP exporter instead of the EMF exporter, and update the on-premises exporter list.
…-end testing Tested on Amazon ECS on Fargate with ADOT Collector v0.50.0 and PromQL queries against the CloudWatch OTLP metrics endpoint. ECS Prometheus: - Use awsvpc network mode. ECS rejects bridge mode with FARGATE. - Add logs:CreateLogGroup to the execution role, which awslogs-create-group needs. - Write ecs_observer targets to /home/aoc, because the image runs as the aoc user and can't write to /etc. - Add cumulative_to_delta, because the endpoint requires a start time on cumulative Prometheus counters. - Drop Prometheus summaries, which the endpoint doesn't accept. - Replace the untested JMX query with the tested NGINX query. ECS metrics receiver: - Drop the receiver's cumulative sums (CPU usage time, network I/O, storage), which have no start time and are rejected by the endpoint. - Use the metrics_transform name instead of the deprecated alias.
The right rail already lists the page's sections. Link the guide's subpages from the existing 'This guide contains' list instead.
Update the site home page callout, which is in home-page.yaml, and the matching tips on the docs home and introduction pages.
lorespiz
approved these changes
Oct 30, 2026
mxiamxia
approved these changes
Oct 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR combines the site cleanup (previously #861) with the technical documentation review.
ADOT predates native OpenTelemetry support in Amazon CloudWatch, and much of this site's technical documentation now conflicts with current AWS guidance — most notably on OTel metrics ingestion, where these docs present the
awsemfexporter as the path while CloudWatch now ingests OTLP natively (https://monitoring.<region>.amazonaws.com/v1/metrics) and recommends the CloudWatch agent. This PR deprecates pages that are superseded and fixes the pages that remain.Site pages and navigation
/videospage along with its section components and JSS styles; remove the Videos header link/aboutpage (components, styles,about-page.yaml), the About header dropdown, and the About footer column/announcementspage,AnnouncementWidget, styles, andannouncements.yaml; remove Latest Announcements from the homepage (Recent Blog Posts is now centered), the Announcements header link, and the Announcements source/search config ingatsby-config.js/searchpage andSearchcomponent, remove the Search header button, and drop the@gatsby-contrib/gatsby-plugin-elasticlunr-searchplugin config and dependency/docs/partners/*pages (Datadog, Dynatrace, Logz.io, Splunk) and the Partners section of the docs sidebar/get-involvedpage andget-involved.yaml; remove its header/footer links and the homepage Join button/contributorspage and the GitHub contributors build plugin (plus itsgithub-base/camelcase-keysdependencies)/resourcespage; remove Contributors and Resources links from the header and footer/contributingand/code-of-conductpages (covered by the repo'sCONTRIBUTING.mdand the Amazon Open Source Code of Conduct); replace the Community header dropdown with a top-level Blog linkAnnouncementBanneris kept since the Lambda docs still use it. No other pages reference the removed files.Deprecated (67 pages → deprecation notices)
Each page keeps its URL (so existing links, including from AWS docs, keep resolving) and now shows a short notice with links to the current documentation. Removed from the docs sidebar.
setup/ecs/): built on an X-Ray SDK sample app and EMF → the rewritten/docs/setup/ecsguide. The ECS console configuration pages point there too.Kept and rewritten:
/docs/setup/ecs. Amazon EKS has the CloudWatch Observability EKS add-on, but on Amazon ECS the ADOT Collector stays the recommended collector. The page now covers running it as a sidecar (CloudFormation templates, or a task definition with the configuration in SSM) that sends traces to the X-Ray OTLP endpoint and metrics to the CloudWatch OTLP endpoint, plus Container Insights, theawsecscontainermetricsreceiver, and moving from the EMF configuration. ECS is back in the Setup sidebar. Merge after aws-observability/aws-otel-collector#3247, which makes the CloudFormation templates default to the OTLP configuration. The page's collector configuration was tested on ADOT Collector v0.50.0: traces, OTLP and StatsD metrics, and theawsecscontainermetricsreceiver against a mock task metadata endpoint.components/otlp-exporterand thedocker-composesample page; deleted 103 images no longer referenced by any pageKept and updated
Pages kept because AWS docs link to them or there is no replacement (EKS add-on install/config, Lambda layer ARNs, X-Ray translation tables, SDK auto-instrumentation, mobile SDKs, EC2/on-prem collector setup, confmap providers, etc.):
Fixes
advanced-prometheus-remote-write-configurations; fixed/v1/api/remote_write→/api/v1/remote_writepipeline:→pipelines:, broken SDK links, added ADOT .NET/Node.js and CloudWatch agent proxyresourcevsresourcesmismatch, broken reinstall/sample-app/troubleshooting links, doubled IRSA/eksctl URLsaws-otel-collector/config.yaml; long-lived access keys in Docker advice removed from X-Ray pagemaster→mainlinks, 404 links, and broken anchorscontainer-insights/eks-fargatewith the ADOT Prometheus sample app (public.ecr.aws/aws-otel-test/prometheus-sample-app)Verification
@mdx-js/mdx1.6.22.adotadd-on configuration schema (aws eks describe-addon-configuration,v0.158.0-eksbuild.1); the schema usesresources, and version examples now referencev0.158.0-eksbuild.1(Kubernetes 1.31–1.37).Follow-ups (not in this PR)
v1alpha1CRs) left unchanged pending verification.adotadd-on's preconfigured collectors only offerxray,emf,amp, andcloudwatchLogspipelines (per its schema) — there is no option to target the CloudWatch OTLP endpoints, so the add-on itself still steers users to the legacy exporters.Open pull requests incorporated or superseded
Applied in this PR (verified against current sources):
podIdentityConfiguration)>=3.10)sql.sanitized_querytypoGITHUB_TOKENpermissions in workflows$→$$escaping note for Prometheus configs on the EKS add-on AMP page (other pages it touched are now deprecated)@opentelemetry/sampler-aws-xray, now published) on the remote sampling pagebracesfrom Bump braces, gatsby, @rocketseat/gatsby-theme-docs, gatsby-plugin-canonical-urls, gatsby-plugin-manifest, gatsby-plugin-offline, gatsby-plugin-react-helmet, gatsby-plugin-remove-trailing-slashes, gatsby-plugin-sass, gatsby-plugin-sitemap, gatsby-source-filesystem, gatsby-transformer-remark and gatsby-transformer-yaml #725: in-range updates (sanitize-htmlpinned to 2.17.0 because 2.18 requires Node 22).npm audit: 192 → 184 findings.Superseded (target pages deprecated or removed): #787 (otlp-exporter removed), #723 (Ruby manual instrumentation), #693 (Windows build page), #554 (Container Insights EKS Prometheus), #538 (.NET manual instrumentation; .NET X-Ray sampling now covered via auto-instrumentation), #304 (2022 metrics GA changes), #690 (
camelcase-keysdependency removed).Not applied: #725 (Gatsby 3 → 5), #710 (
@rocketseat/gatsby-theme-docs2 → 4), and #709 (npm8 → 10) are major upgrades that need a separate migration; most remaining high/critical audit findings depend on the Gatsby upgrade.Build verified locally with Node 16 (
npm ci && npm run build, same as CI).Testing
be31198and checked every internal link in the output. Of 7,931 links on 279 pages, one is broken, and it's already broken onmain: the EKS add-on v0.88.0 release blog links to/docs/getting-started/adot-eks-add-on/add-on-v88-migration, which was removed in 36aff49. All internal links on the rewritten ECS guide and the 21 ECS stubs resolve, and all 10 external links on the ECS guide return 200.debugexporter.otlp_httpexporters to the X-Ray and CloudWatch endpoints start.awsecscontainermetricssnippet: ran it against a mock task metadata endpoint built from the receiver's upstream fixtures. It produced 54ecs.task.*/container.*metrics withaws.ecs.*attributes and the CloudWatch-style units the guide describes.b0efdf2on Fargate. Spans arrived in Transaction Search andjvm.memory.usedcould be queried with PromQL.Lambda updates (merged from #863)
Summary
Updates the Lambda pages to match the published ADOT Lambda layers and current Lambda runtimes, and replaces the legacy Go guide with a tested setup that sends traces to the X-Ray OTLP endpoint.
Layer versions and runtimes
Java ARNs: updated to v2.32.0 (
AWSOpenTelemetryDistroJava:19in most Regions) for all 35 Regions, from the v2.32.0 release notes. Python (:32), JavaScript (:16), and .NET (:15) were already current.Supported runtimes: the table now lists the runtimes each layer declares and Lambda supports, with a new Architectures column:
New notes under Supported Runtimes:
RequestHandlerorRequestStreamHandler; other handlers run but produce no spans.provided.al2023functions have no Application Signals layer. The note links to the Go guide.Go guide
The previous guide targeted
provided.al2, which Lambda has deprecated, and used the collector layer's defaultawsxrayexporter. The new guide covers:provided.al2023, on x86_64 or arm64.otellambda/xrayconfig, plusotelhttpfor outgoing requests.aws-otel-collector-<arch>-ver-0-156-0:4, still the latest), with acollector.yamlthat exports tohttps://xray.<region>.amazonaws.com/v1/tracesthroughotlp_httpandsigv4auth. The file is loaded withOPENTELEMETRY_COLLECTOR_CONFIG_URI=/var/task/collector.yaml.OTEL_SERVICE_NAME. Without it, Go SDK spans have noservice.name.Testing
End to end in us-east-1 (Transaction Search enabled), each function invoked 5 times. All test resources were deleted afterwards.
AWSOpenTelemetryDistroPython:32aws/spans; listed in Application Signals (lambda:default) with Latency, Error, Fault, ThrottleAWSOpenTelemetryDistroJs:16AWSOpenTelemetryDistroJava:18and:19RequestStreamHandlerhandler)AWSOpenTelemetryDistroDotNet:15provided.al2023)aws-otel-collector-amd64-ver-0-156-0:4with the guide'scollector.yamlotellambdaserver andotelhttpclient spans inaws/spans, withservice.namefromOTEL_SERVICE_NAME; collector logged no warnings; listed in Application Signals with the same metricsThe guide's Go code and
collector.yamlare identical to the tested files. The site builds with these changes merged onto #862, with no new warnings, and all internal links on both pages resolve.Follow-ups (not in this PR)
System.IO.Streamfailed under the ADOT .NET wrapper, which deserializes the event into the handler's parameter type. This was seen with a non-standard package and needs checking with a standard one.2.31.1-adot-lambda1-alphaand2.32.0-adot-lambda1-alpha. Is the "alpha" suffix intended?The Go guide now refers to the CloudWatch OTLP traces endpoint, matching the rest of this pull request.