Merge remote-tracking branch 'origin/main' into otelbot/spec-integration-v1.52.0-dev

Author: otelbot[bot]

config/_default/hugo.yaml

@@ -57,6 +57,8 @@ languages:
     params:
       description: OpenTelemetry 项目网站
 
+enableEmoji: true
+
 imaging:
   resampleFilter: CatmullRom # cspell:disable-line
   quality: 75

content/en/blog/2024/spring-starter-stable/index.md

@@ -79,7 +79,7 @@ Note that the Spring Starter uses some semantic conventions that are not stable,
 which are still evolving and may change in the future.
 [HTTP semantic conventions](/docs/specs/semconv/http/http-metrics/) are stable
 and will not change.
-[Database semantic conventions](/docs/specs/semconv/database/database-metrics/)
+[Database semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/database/database-metrics.md)
 are still experimental and may change. However, they are expected to become
 stable at the end of 2024.
 

content/en/blog/2025/complex-attribute-types.md

@@ -71,8 +71,9 @@ Examples include:
   inherently structured
 - **GraphQL** — responses may include
   [lists of structured errors](https://graphql.org/learn/response/#errors)
-- **[Database operations](/docs/specs/semconv/database/database-spans)** — batch
-  operations have properties that flat attributes cannot adequately capture
+- **[Database operations](https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/database/database-spans.md)**
+  — batch operations have properties that flat attributes cannot adequately
+  capture
 
 Before extending support for complex attributes to all signals, we explored
 several alternatives:

content/en/community/end-user/_index.md

@@ -101,7 +101,7 @@ CNCF Slack! Not there yet?
 
 {{% alert title="For OpenTelemetry contributors" %}}
 
-Is your SIG in need of insights from end users?:female-detective: Are you
+Is your SIG in need of insights from end users? :female_detective: Are you
 wanting to find out whether end users are using or even aware of a feature your
 SIG has developed? Or perhaps you're looking for some general feedback about the
 thing you've spent hours working on? Reach out to the End User SIG on Slack

content/en/docs/collector/_index.md

@@ -2,6 +2,7 @@
 title: Collector
 description: Vendor-agnostic way to receive, process and export telemetry data.
 aliases: [./about]
+sidebar_root_for: children
 cascade:
   vers: 0.140.0
 weight: 270

content/en/docs/collector/deployment/_index.md

@@ -1,21 +1,22 @@
 ---
-title: Deployment
-description: Patterns you can apply to deploy the OpenTelemetry collector
+title: Deploy the Collector
+linkTitle: Deploy
+description: Patterns you can apply to deploy the OpenTelemetry Collector
 weight: 3
 ---
 
-The OpenTelemetry Collector consists of a single binary which you can use in
-different ways, for different use cases. This section describes deployment
-patterns, their use cases along with pros and cons and best practices for
-collector configurations for cross-environment and multi-backend deployments.
-For deployment security considerations, see [Collector hosting best
+The OpenTelemetry Collector consists of a single binary that you can deploy in
+different ways for different use cases. This section describes common deployment
+patterns, their use cases, and pros and cons. It also provides best practices
+for configuring the Collector in cross-environment and multi-backend scenarios.
+For deployment-related security considerations, see the [Collector hosting best
 practices][security].
 
-## Resources
+## Additional resources
 
-- KubeCon NA 2021 Talk on [OpenTelemetry Collector Deployment
+- KubeCon NA 2021 talk on [OpenTelemetry Collector Deployment
   Patterns][y-patterns]
-- [Deployment Patterns][gh-patterns] accompanying the talk
+  - [Deployment patterns][gh-patterns] accompanying the talk
 
 [security]: /docs/security/hosting-best-practices/
 [gh-patterns]:

content/en/docs/collector/deployment/agent.md

@@ -6,35 +6,37 @@ weight: 2
 cSpell:ignore: prometheusremotewrite
 ---
 
-The agent collector deployment pattern consists of applications —
-[instrumented][instrumentation] with an OpenTelemetry SDK using [OpenTelemetry
-protocol (OTLP)][otlp] — or other collectors (using the OTLP exporter) that send
-telemetry signals to a [collector][] instance running with the application or on
-the same host as the application (such as a sidecar or a daemonset).
+In the agent deployment pattern, telemetry signals can come from
 
-Each client-side SDK or downstream collector is configured with a collector
-location:
+- Applications [instrumented][instrumentation] with an OpenTelemetry SDK using
+  the [OpenTelemetry Protocol (OTLP)][otlp]
+- Collectors using the OTLP exporter
+
+The signals are sent to a [Collector][collector] instance that runs alongside
+the application or on the same host, such as a sidecar or DaemonSet.
+
+Each client-side SDK or downstream Collector is configured with the address of a
+Collector instance:
 
 ![Decentralized collector deployment concept](../../img/otel-agent-sdk.svg)
 
-1. In the app, the SDK is configured to send OTLP data to a collector.
-1. The collector is configured to send telemetry data to one or more backends.
+1. In the application, the SDK is configured to send OTLP data to a Collector.
+1. The Collector is configured to send telemetry data to one or more backends.
 
 ## Example
 
-A concrete example of the agent collector deployment pattern could look as
-follows: you manually instrument, say, a [Java application to export
-metrics][instrument-java-metrics] using the OpenTelemetry Java SDK. In the
-context of the app, you would set the `OTEL_METRICS_EXPORTER` to `otlp` (which
-is the default value) and configure the [OTLP exporter][otlp-exporter] with the
-address of your collector, for example (in Bash or `zsh` shell):
+In this example of the agent deployment pattern, begin by manually instrumenting
+a [Java application to export metrics][instrument-java-metrics] using the
+OpenTelemetry Java SDK, including the default `OTEL_METRICS_EXPORTER` value,
+`otlp`. Next, configure the [OTLP exporter][otlp-exporter] with the address of
+your Collector. For example:
 
 ```shell
 export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
 ```
 
-The collector serving at `collector.example.com:4318` would then be configured
-like so:
+Next, configure the Collector running at `collector.example.com:4318` as
+follows:
 
 {{< tabpane text=true >}} {{% tab Traces %}}
 
@@ -103,20 +105,22 @@ service:
 
 {{% /tab %}} {{< /tabpane >}}
 
-If you want to try it out for yourself, you can have a look at the end-to-end
-[Java][java-otlp-example] or [Python][py-otlp-example] examples.
+To explore this pattern end to end, see the [Java][java-otlp-example] or
+[Python][py-otlp-example] examples.
+
+## Trade-offs
 
-## Tradeoffs
+Here are the key pros and cons of using an agent collector:
 
 Pros:
 
-- Simple to get started
-- Clear 1:1 mapping between application and collector
+- Straightforward to get started
+- Clear one-to-one mapping between application and Collector
 
 Cons:
 
-- Scalability (human and load-wise)
-- Inflexible
+- Limited scalability for teams and infrastructure resources
+- Inflexible for complex or evolving deployments
 
 [instrumentation]: /docs/languages/
 [otlp]: /docs/specs/otel/protocol/

content/en/docs/collector/deployment/no-collector.md

@@ -1,32 +1,34 @@
 ---
 title: No Collector
-description: Why and how to send signals directly from app to backends
+description:
+  Why and how to send signals directly from an application to backends
 weight: 1
 ---
 
-The simplest pattern is not to use a collector at all. This pattern consists of
-applications [instrumented][instrumentation] with an OpenTelemetry SDK that
-export telemetry signals (traces, metrics, logs) directly into a backend:
+The most direct deployment pattern doesn't use a Collector at all. In this
+approach, applications [instrumented][instrumentation] with an OpenTelemetry SDK
+export telemetry signals (traces, metrics, and logs) straight to a backend:
 
 ![No collector deployment concept](../../img/otel-sdk.svg)
 
 ## Example
 
-See the [code instrumentation for programming languages][instrumentation] for
-concrete end-to-end examples for how to export signals from your app directly
-into a backend.
+See the [instrumentation documentation][instrumentation] for end-to-end examples
+that show how to export signals directly from your application to a backend.
 
-## Tradeoffs
+## Trade-offs
+
+Here are the key pros and cons of skipping the Collector:
 
 Pros:
 
-- Simple to use (especially in a dev/test environment)
-- No additional moving parts to operate (in production environments)
+- Straightforward to use, especially in development and test environments
+- No additional moving parts to deploy or operate
 
 Cons:
 
-- Requires code changes if collection, processing, or ingestion changes
-- Strong coupling between the application code and the backend
-- There are limited number of exporters per language implementation
+- Requires code changes if collection, processing, or ingestion needs change
+- Strong coupling between application code and backend storage or visualization
+- Each language implementation supports only a limited number of exporters
 
 [instrumentation]: /docs/languages/

content/en/docs/contributing/_index.md

@@ -3,9 +3,43 @@ title: Contributing
 aliases: [/docs/contribution-guidelines]
 sidebar_root_for: self
 weight: 980
+cascade:
+  chooseAnIssueAtYourLevel: |
+    Make sure to [choose an issue] that matches your level of **experience** and
+    **understanding** of OpenTelemetry. Avoid overreaching your capabilities.
+  _issues: https://github.com/open-telemetry/opentelemetry.io/issues
+  _issue: https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A
 ---
 
-Thanks for your interest in contributing to the OpenTelemetry docs and website.
+{{% alert title="Thank you for your interest!" color=success %}}
+
+Thank you for your interest in contributing to the OpenTelemetry docs and
+website.
+
+{{% /alert %}}
+
+## <i class='far fa-exclamation-triangle text-warning '></i> First time contributing? {#first-time-contributing}
+
+- **[Choose an issue]** with the following labels:
+  - [Good first issue](<{{% param _issue %}}%22good+first+issue%22>)
+  - [Help wanted](<{{% param _issue %}}%3A%22help+wanted%22>)
+
+  {{% alert title="We do not assign issues" color="warning" %}}
+
+  We **_do not_ assign issues** to those who have not already made contributions
+  to the [OpenTelemetry organization][org], unless part of a confirmed
+  mentorship or onboarding process.
+
+  [org]: https://github.com/open-telemetry
+
+  {{% /alert %}}
+
+- {{% param chooseAnIssueAtYourLevel %}}
+
+- Want to work other issues or larger changes? [Discuss it with maintainers
+  first][].
+
+[discuss it with maintainers first]: issues/#fixing-an-existing-issue
 
 ## Jump right in!
 
@@ -20,17 +54,8 @@ What do you want to do?
   - [Submitting content]
 
 [Prerequisites]: prerequisites/
-[Issues]: issues/
 [Submitting content]: pull-requests/
 
-{{% alert title="<i class='far fa-exclamation-triangle'></i> First time contributing? " %}}
-
-Eager first-time contributors, see
-[Fixing an existing issue](issues/#fixing-an-existing-issue) for important
-guidance.
-
-{{% /alert %}}
-
 ## What can I contribute to?
 
 OpenTelemetry documentation contributors:
@@ -48,6 +73,7 @@ the community [OpenTelemetry New Contributor Guide]. Every [OTel
 repository][org] for language implementations, the Collector, and conventions
 have their own project-specific contributing guides.
 
+[choose an issue]: issues/#fixing-an-existing-issue
+[issues]: issues/
 [OpenTelemetry New Contributor Guide]:
   https://github.com/open-telemetry/community/blob/main/guides/contributor
-[org]: https://github.com/open-telemetry

content/en/docs/contributing/issues.md

@@ -5,50 +5,20 @@ description:
   improvement.
 weight: 10
 _issues: https://github.com/open-telemetry/opentelemetry.io/issues
-_issue: https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A
 cSpell:ignore: prepopulated
 ---
 
-<style>
-  /* Force all list to be compact. */
-  li > p {
-    margin-bottom: 0;
-  }
-
-  /* Style "first time" alert */
-  .alert--first-timer {
-    margin: 0.5rem 0 !important;
-
-    > blockquote {
-      margin-top: 1rem;
-      margin-bottom: 0;
-      border-left-color: var(--bs-warning);
-      background-color: var(--bs-danger-bg-subtle);
-      > *:last-child {
-        margin-bottom: 0;
-      }
-    }
-  }
-</style>
-
 ## Fixing an existing issue
 
-One of the best ways to help make OTel docs better is to fix an existing issue.
+One of the best ways to help improve the documentation is to fix an existing
+issue.
 
 1. Browse through the list of [issues]({{% param _issues %}}).
-2. Select an issue that you would like to work on, ideally one that you can fix
-   in a short amount of time. <a name="first-issue"></a>
-   {{% alert title="First time contributing?" color="primary alert--first-timer" %}}
-
-   Select an issue with the following labels:
-   - [Good first issue](<{{% param _issue %}}%22good+first+issue%22>)
-   - [Help wanted](<{{% param _issue %}}%3A%22help+wanted%22>)
-
-   > **NOTE**: we **_do not_ assign issues** to those who have not already made
-   > contributions to the [OpenTelemetry organization][org], unless part of a
-   > mentorship or onboarding process.
-   >
-   > [org]: https://github.com/open-telemetry
+2. Select an issue that you would like to work on.
+
+   {{% alert color="warning" %}}
+
+   {{% param chooseAnIssueAtYourLevel %}}
 
    {{% /alert %}}