Merge remote-tracking branch 'origin/main' into otelbot/semconv-integration-v1.40.0-dev

Author: otelbot[bot]

.cspell.yml

@@ -89,7 +89,7 @@ words:
   - Crossplane
   - crosspost
   - desaturate
-  - Docsy
+  - docsy
   - errorf
   - excerpter
   - favicons

.cspell/en-words.txt

@@ -16,6 +16,7 @@ autoloaded
 autoloader
 autoloading
 backoff
+blockquotes
 caml
 cartservice
 cassandra

.markdownlint-cli2.yaml

@@ -1,4 +1,5 @@
 customRules:
+  - ./scripts/_md-rules/prefer-blockquote-vs-docsy-alerts/index.mjs
   - ./scripts/_md-rules/alert-type-not-translated.mjs
   - ./scripts/_md-rules/unindent-code-blocks.js
   - ./scripts/_md-rules/trim-code-blank-lines.js

.markdownlint.yaml

@@ -41,6 +41,10 @@ table-column-style: false # Causes problems in ja and zh pages
 
 gh-url-hash: false
 
+# Prefer blockquote alerts in English docs; enabled under content/en only. See
+# content/en/.markdownlint.yaml.
+prefer-blockquote-vs-docsy-alerts: false
+
 # Custom rules registered in .markdownlint-cli2.yaml are enabled by default
 # (via `default: true` above). Only list custom rules here to disable them or
 # to provide configuration. Rules that need no config can be omitted.

content/en/.markdownlint.yaml

@@ -0,0 +1,3 @@
+extends: ../../.markdownlint.yaml
+
+prefer-blockquote-vs-docsy-alerts: true

content/en/blog/2026/otel-php-distro-donation-update.md

@@ -0,0 +1,98 @@
+---
+title: OpenTelemetry Accepted Elastic's PHP Distro Donation
+linkTitle: Elastic PHP Distro Donation
+date: 2026-04-16
+author: >-
+  [Pawel Filipczak](https://github.com/intuibase) (Elastic)
+draft: true
+issue: https://github.com/open-telemetry/opentelemetry.io/issues/9434
+sig: OpenTelemetry PHP
+cSpell:ignore: Filipczak Pawel
+---
+
+The OpenTelemetry community accepted the donation of the OpenTelemetry PHP
+Distro project. This post summarizes what the donation enables, how it relates
+to existing PHP instrumentation paths, and where contributors can help next.
+
+## Why this donation matters
+
+OpenTelemetry provides a common observability standard, but OpenTelemetry PHP
+adoption can still be difficult in environments where installing or compiling
+native extensions is restricted. Common blockers include:
+
+- Restricted or hardened systems where native extensions cannot be built during
+  deployment.
+- Runtime images that are not rebuilt frequently.
+- Operational workflows that rely on OS package managers.
+
+The PHP Distro addresses these constraints by focusing on an operations-first
+installation model.
+
+## What the PHP Distro provides
+
+The project combines native and PHP runtime components into a single deployment
+model for production environments. Current capabilities include:
+
+- Prebuilt native extension and loader artifacts.
+- Runtime/bootstrap logic for auto-instrumentation.
+- Packaging support for `deb`, `rpm`, and `apk`.
+- OTLP protobuf serialization without requiring `ext-protobuf`.
+- Inferred spans and URL grouping features for better visibility.
+- OpAMP integration support.
+
+For teams running PHP `8.1` through `8.4`, this can reduce adoption overhead
+compared with custom build pipelines.
+
+## Relationship to existing PHP instrumentation
+
+The distro builds on the same OpenTelemetry PHP APIs and SDK, so it does not
+fork or replace core components. Teams can choose either installation path on a
+per-service basis:
+
+- Distro path: package-managed, operations-first rollout with minimal code
+  changes.
+- Composer-based path: manual control and portability where application-level
+  packaging is preferred.
+
+Choosing between them depends on your deployment model, security constraints,
+and ownership of runtime packaging.
+
+## Practical rollout checklist
+
+Before broad production rollout, validate the following:
+
+- Runtime compatibility across PHP versions and SAPIs (`php-fpm`, `mod_php`,
+  CLI).
+- Package format and architecture support in your Linux distributions.
+- Telemetry quality (span completeness, naming, exporter behavior).
+- Operational safety (restart and rollback procedures, version pinning).
+
+A lightweight validation matrix across representative services can help avoid
+rework later.
+
+## Current status and next topics
+
+The project has reached a major milestone and is moving toward a first beta
+release. Active follow-up topics include:
+
+- Class and namespace shadowing to reduce dependency collisions.
+- Declarative configuration support.
+- PHP `8.5` compatibility.
+- Central configuration capabilities aligned with OpenTelemetry policy work.
+- Ongoing alignment between upstream OpenTelemetry distro work and vendor
+  distributions built on top of it.
+
+## How to contribute
+
+If you want to help:
+
+- Test the distro in real environments and share compatibility findings.
+- Report installation and runtime issues in
+  [`opentelemetry-php-distro` repository](https://github.com/open-telemetry/opentelemetry-php-distro).
+- Propose documentation improvements for deployment, migration, and
+  troubleshooting.
+- Join OpenTelemetry PHP and relevant SIG discussions to align roadmap and user
+  guidance.
+
+You can also review the donation context and discussion in
+[open-telemetry/community issue #2846](https://github.com/open-telemetry/community/issues/2846).

content/en/docs/collector/quick-start.md

@@ -1,96 +1,108 @@
 ---
 title: Quick start
-description: Setup and collect telemetry in minutes!
+description: Set up and collect telemetry in minutes!
 aliases: [getting-started]
 weight: 1
 cSpell:ignore: docker dokey gobin okey telemetrygen
 ---
 
 <!-- markdownlint-disable ol-prefix blanks-around-fences -->
 
-The OpenTelemetry Collector receives [traces](/docs/concepts/signals/traces/),
+The OpenTelemetry Collector receives telemetry such as
+[traces](/docs/concepts/signals/traces/),
 [metrics](/docs/concepts/signals/metrics/), and
-[logs](/docs/concepts/signals/logs/), processes the telemetry, and exports it to
-a wide variety of observability backends using its components. For a conceptual
-overview of the Collector, see [Collector](/docs/collector).
+[logs](/docs/concepts/signals/logs/), processes it, and forwards it to one or
+more observability backends through its component pipeline.
 
-You are going to learn to do the following in less than five minutes:
+> [!NOTE]
+>
+> This quick start demo creates a basic local setup. The goal is to show you how
+> the Collector works, not to set up a production-ready environment.
 
-- Set up and run the OpenTelemetry Collector.
-- Send telemetry and see it processed by the Collector.
+In this guide, you will:
+
+- Start a local instance of the OpenTelemetry Collector
+- Generate trace data and send it to the Collector
+- Check that the Collector receives and processes the data
+
+By the end, you will have a simple pipeline running on your machine and a
+clearer idea of how the Collector fits into an observability stack. If you want
+more context before getting started, see the [Collector](/docs/collector)
+overview.
 
 ## Prerequisites
 
-Make sure that your developer environment has the following. This page assumes
-that you're using `bash`. Adapt configuration and commands as necessary for your
-preferred shell.
+Before you begin, make sure your environment has the following tools installed:
+
+- [Docker](https://www.docker.com/) or any compatible container runtime — used
+  to run the Collector
+- [Go](https://go.dev/), one of the latest two minor versions — used to install
+  the telemetry generator
+- [`GOBIN` environment variable][gobin] set — ensures installed Go binaries are
+  available in your PATH[^1]
 
-- [Docker](https://www.docker.com/) or any compatible containers' runtime.
-- [Go](https://go.dev/) 1.20 or higher
-- [`GOBIN` environment variable][gobin] is set; if unset, initialize it
-  appropriately, for example[^1]:
-  ```sh
-  export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
-  ```
+If `GOBIN` isn't set, run:
+
+```sh
+export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
+```
+
+This guide uses `bash` commands. If you're using a different shell, you might
+need to adjust the command syntax.
 
 [^1]:
     For more information, see
     [Your first program](https://go.dev/doc/code#Command).
 
 ## Set up the environment
 
-1. Pull in the OpenTelemetry Collector core Docker image:
+1. Pull the Docker image of the OpenTelemetry Collector core
+   [distribution](/docs/collector/distributions/):
 
    ```sh
    docker pull otel/opentelemetry-collector:{{% param vers %}}
    ```
 
-2. Install the [telemetrygen][] utility:
+2. Install [telemetrygen][], which we'll use to simulate a client that generates
+   telemetry:
 
    ```sh
    go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
    ```
 
-   This utility can simulate a client generating [traces][], [metrics][], and
-   [logs][].
-
 ## Generate and collect telemetry
 
-3. Launch the Collector, listening on ports 4317 (for OTLP gRPC), 4318 (for OTLP
-   HTTP) and 55679 (for ZPages):
+3. Start the Collector:
 
    ```sh
    docker run \
      -p 127.0.0.1:4317:4317 \
      -p 127.0.0.1:4318:4318 \
      -p 127.0.0.1:55679:55679 \
      otel/opentelemetry-collector:{{% param vers %}} \
-     2>&1 | tee collector-output.txt # Optionally tee output for easier search later
+     2>&1 | tee collector-output.txt
    ```
 
-4. In a separate terminal window, generate a few sample traces:
+   The previous command runs the Collector locally and opens three ports:
+   - `4317` — OTLP over gRPC, the default for most SDKs
+   - `4318` — OTLP over HTTP, for clients that don't support gRPC
+   - `55679` — ZPages, a built-in debug UI you can open in the browser
+
+4. In a separate terminal, generate some traces:
 
    ```sh
    $GOBIN/telemetrygen traces --otlp-insecure --traces 3
    ```
 
-   Among the output generated by the utility, you should see a confirmation that
-   traces were generated:
+   You see output confirming the traces were sent:
 
    ```text
    2024-01-16T14:33:15.692-0500  INFO  traces/worker.go:99  traces generated  {"worker": 0, "traces": 3}
    2024-01-16T14:33:15.692-0500  INFO  traces/traces.go:58  stop the batch span processor
    ```
 
-   For an easier time seeing relevant output you can filter it:
-
-   ```sh
-   $GOBIN/telemetrygen traces --otlp-insecure \
-     --traces 3 2>&1 | grep -E 'start|traces|stop'
-   ```
-
-5. In the terminal window running the Collector container, you should see trace
-   ingest activity similar to what is shown in the following example:
+5. Back in the Collector terminal, you should see trace ingest activity similar
+   to the following:
 
    ```console
    $ grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txt
@@ -117,30 +129,27 @@ preferred shell.
    ...
    ```
 
-6. Open <http://localhost:55679/debug/tracez> and select one of the samples in
-   the table to see the traces you've just generated.
+6. To explore the traces visually, open <http://localhost:55679/debug/tracez> in
+   your browser and select one of the traces from the table.
 
-7. After you are done, shutdown the Collector container, for example, using
-   <kbd>Control-C</kbd>.
+7. Press <kbd>Control-C</kbd> to stop the Collector.
 
 ## Next steps
 
-In this tutorial you've started the OpenTelemetry Collector and sent telemetry
-to it. As next steps, consider doing the following:
+At this point, you've run the Collector locally and seen how it handles
+telemetry end to end. From here, you can start learning how it's used in real
+setups:
 
-- Explore different ways to [install the Collector](/docs/collector/install/).
-- Learn about the different modes of the Collector in
-  [Deployment Methods](/docs/collector/deploy/).
-- Familiarize yourself with the Collector
-  [configuration](/docs/collector/configuration) files and structure.
-- Explore available components in the
-  [registry](/ecosystem/registry/?language=collector).
-- Learn how to
-  [build a custom Collector with the OpenTelemetry Collector Builder (OCB)](/docs/collector/extend/ocb/).
+- [Configuration](/docs/collector/configuration): Learn how the Collector's
+  config file works and how to connect it to a real backend like Jaeger or
+  Prometheus.
+- [Deployment patterns](/docs/collector/deploy/): Understand the difference
+  between running the Collector as an agent versus a gateway.
+- [Install the Collector](/docs/collector/install/): Explore installation
+  options beyond Docker, including binaries and Kubernetes.
+- [Component registry](/ecosystem/registry/?language=collector): Browse
+  available receivers, processors, and exporters to extend your pipeline.
 
 [gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables
-[logs]: /docs/concepts/signals/logs/
-[metrics]: /docs/concepts/signals/metrics/
 [telemetrygen]:
   https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen
-[traces]: /docs/concepts/signals/traces/

content/en/docs/contributing/sig-practices.md

@@ -5,7 +5,7 @@ description:
   Learn how approvers and maintainers manage issues and contributions.
 weight: 999
 # prettier-ignore
-cSpell:ignore: Comms contribfest docsy hotfixes inactivitiy onboarded triager triagers
+cSpell:ignore: Comms contribfest hotfixes inactivitiy onboarded triager triagers
 ---
 
 This pages includes guidelines and some common practices used by approvers and

content/en/docs/contributing/style-guide.md

@@ -130,6 +130,10 @@ To enforce standards and consistency for Markdown files, all files should follow
 certain rules, enforced by [markdownlint][]. For a full list, check the
 [.markdownlint.yaml][] and [.markdownlint-cli2.yaml][] files.
 
+When legitimate exceptions to a rule exists, use `markdownlint-disable`
+directive to suppress the rule warnings. For details, see the
+[markdownlint documentation](https://github.com/DavidAnson/markdownlint#configuration).
+
 We also enforce Markdown [file format](#file-format) and strip files of trailing
 whitespace. This precludes the [line break syntax][] of 2+ spaces; use `<br>`
 instead or reformat your text.