Merge branch 'main' into fix-path-zero-code-instrumentation

Author: vitorvasc

.gitmodules

@@ -1,7 +1,8 @@
+# cSpell:ignore docsy javaexamples
 [submodule "themes/docsy"]
 	path = themes/docsy
 	url = https://github.com/google/docsy.git
-	docsy-pin = v0.11.0-2-g68aa7b3
+	docsy-pin = v0.11.0-22-g2f361b2b
 	docsy-note = "2024-04-01 Switching to google/docsy.git from cncf/docsy.git since we don't have any CNCF customizations."
 	docsy-reminder = "Ensure that any tag referenced by `docsy-pin` is present in the remote repo (url), otherwise add (push) the tags to the repo."
 [submodule "content-modules/opentelemetry-specification"]

.htmltest.yml

@@ -10,6 +10,8 @@ IgnoreDirs:
   # DO NOT EDIT! IgnoreDirs list is auto-generated from markdown file front matter.
   # Ignore blog index pages for all locales and in all blog sections (top-level and years)
   - ^(../)?blog/(\d+/)?page/\d+
+  # Ignore old blog posts
+  - ^(../)?blog/20(19|21|22|23)/
   # TODO drop next lines after https://github.com/open-telemetry/opentelemetry.io/issues/5555 is fixed for these pages:
   - ^zh/docs/concepts/signals/baggage/
   - ^zh/docs/zero-code/php/

content/en/blog/2023/otel-arrow/index.md

@@ -140,7 +140,7 @@ aligning OpenTelemetry more closely with modern data pipelines that are
 increasingly pivoting towards Apache Arrow.
 
 A specification for this protocol (OTEP 0156) can be found
-[here](https://github.com/open-telemetry/oteps/blob/main/text/0156-columnar-encoding.md).
+[here](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0156-columnar-encoding.md).
 A reference implementation of the encoding/decoding function can be accessed
 [here](https://github.com/open-telemetry/otel-arrow).
 
@@ -269,7 +269,7 @@ invaluable assistance.
 ## Links
 
 - OpenTelemetry Protocol with Apache Arrow Specification -
-  [OTEP 0156](https://github.com/open-telemetry/oteps/blob/main/text/0156-columnar-encoding.md)
+  [OTEP 0156](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0156-columnar-encoding.md)
 - OpenTelemetry Protocol with Apache Arrow (encoder/decoder)
   [repository](https://github.com/open-telemetry/otel-arrow).
 - Receiver

content/en/blog/2024/fuzzing-audit-results.md

@@ -0,0 +1,75 @@
+---
+title: OpenTelemetry Collector Completes Fuzzing Audit
+linkTitle: Fuzzing Audit Results
+date: 2024-12-20
+author: '[Adam Korczynski](https://github.com/AdamKorcz)'
+issue: 5798
+sig: GC
+cSpell:ignore: containerd Korczynski
+---
+
+OpenTelemetry is happy to announce the completion of the Collector's fuzzing
+audit [sponsored by the CNCF] and carried out by
+[Ada Logics](https://adalogics.com/). The audit marks a significant step in the
+OpenTelemetry project, ensuring the security and reliability of the Collector
+for its users.
+
+[sponsored by the CNCF]:
+  https://contribute.cncf.io/resources/project-services/audits/
+
+## What is fuzzing?
+
+Fuzzing is a testing technique that executes an API with a high amount of
+pseudo-random inputs and observes the API's behavior. The technique has
+increased in popularity due to its empirical success in finding security
+vulnerabilities and reliability issues. Fuzzing initially developed with a focus
+on testing software implemented in memory-unsafe languages, where it has been
+most productive. However, in recent years, fuzzing has expanded to memory-safe
+languages as well.
+
+Over several years, the CNCF has invested in fuzzing for its ecosystem. This
+testing has found numerous security vulnerabilities in widely used projects such
+as Helm (CVE-2022-36055, CVE-2022-23524, CVE-2022-23526, CVE-2022-23525), the
+Notary project (CVE-2023-25656), containerd (CVE-2023-25153), Crossplane
+(CVE-2023-28494, CVE-2023-27483) and Flux (CVE-2022-36049).
+
+## OSS-Fuzz
+
+To initiate the audit, Ada Logics auditors integrated the OpenTelemetry
+Collector into [OSS-Fuzz](https://github.com/google/oss-fuzz). OSS-Fuzz is a
+service offered by Google to critical open source projects, free of charge. The
+service runs a project's fuzzers with excess resources multiple times per week.
+If OSS-Fuzz finds a crash, it notifies the project. It then checks if the
+project has fixed the crash upstream and if so, marks the issue(s) as fixed. The
+whole workflow happens continuously on Google's fuzzing infrastructure,
+supported by thousands of CPU cores. These testing resources outperform what
+developers or malicious threat actors can muster.
+
+## The tests
+
+After the Ada Logics team integrated OpenTelemetry into OSS-Fuzz, the next step
+was to write a series of fuzz tests for the OpenTelemetry Collector. The
+auditors wrote 49 fuzz tests for core components of the Collector, as well as
+several receivers and processors in the `opentelemetry-collector-contrib`
+repository.
+
+The fuzz tests were left to run while the audit team observed their health in
+production. At the completion of the fuzzing audit, the 49 fuzz tests on the
+OSS-Fuzz platform were healthy.
+
+To ensure continued reliability, the fuzz testing continues on the Collector
+even though the audit is complete.
+
+## The results so far
+
+Fuzz testing for the Collector is ongoing, allowing for changes to the project
+to be tested as well. As of the date of this post, no crashes have been
+detected.
+
+But the work is not done! The Ada Logics team created the Collector's fuzzing
+setup as a reference implementation that other OpenTelemetry subprojects can
+rely on to create their own fuzz testing, ensuring greater stability for the
+project as a whole.
+
+For more insight into the audit process, see the
+[published summary](https://github.com/open-telemetry/community/blob/main/reports/ADA_Logics-collector-fuzzing-audit-2024.pdf).

content/en/blog/2024/humans-of-otel-na-2024.md

@@ -1,5 +1,5 @@
 ---
-title: The Humans OpenTelemetry - KubeCon NA 2024
+title: The Humans of OpenTelemetry - KubeCon NA 2024
 linkTitle: Humans of OTel NA 2024
 date: 2024-12-19
 author: >-

content/en/blog/2024/otel-arrow-production/index.md

@@ -54,7 +54,7 @@ The compression bridge consists of two OpenTelemetry Collectors labeled exporter
 and receiver, or they could equally be two pools of load-balanced collectors.
 
 As described in the
-[OTEP 0156 design document](https://github.com/open-telemetry/oteps/blob/main/text/0156-columnar-encoding.md#mapping-otel-entities-to-arrow-records),
+[OTEP 0156 design document](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0156-columnar-encoding.md#mapping-otel-entities-to-arrow-records),
 the exporter converts arbitrary OpenTelemetry data into an Arrow record batch.
 The Arrow record batch is a block of memory, with a standardized layout, making
 it possible to exchange data across address spaces and virtual process

content/en/blog/2024/profiling.md

@@ -58,7 +58,7 @@ utilization at a code-level and allows for this profiling data to be stored,
 queried, and analyzed over time and across different attributes. It’s an
 important technique for developers and performance engineers to understand
 exactly what’s happening in their code. OpenTelemetry’s
-[profiling signal](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0239-profiles-data-model.md)
+[profiling signal](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/profiles/0239-profiles-data-model.md)
 expands upon the work that has been done in this space and, as a first for the
 industry, connects profiles with other telemetry signals from applications and
 infrastructure. This allows developers and operators to correlate resource

content/en/blog/2024/year-in-review.md

@@ -217,8 +217,13 @@ You can also join us:
 
 Together, we can make 2025 another amazing year for [opentelemetry.io](/)!
 
+_[Cross-posted] to the [CNCF blog]._
+
+[CNCF blog]: https://www.cncf.io/blog/
 [Comms meetings]:
   https://docs.google.com/document/d/1wW0jLldwXN8Nptq2xmgETGbGn9eWP8fitvD5njM-xZY
+[Cross-posted]:
+  https://www.cncf.io/blog/2024/12/20/opentelemetry-io-2024-review/
 [discussions]: https://github.com/open-telemetry/opentelemetry.io/discussions
 [get involved]: /docs/contributing/
 [issues]: https://github.com/open-telemetry/opentelemetry.io/issues

content/en/blog/2025/_index.md

@@ -0,0 +1,5 @@
+---
+title: 2025
+weight: -2025
+outputs: [HTML, RSS]
+---

content/en/blog/_index.md

@@ -8,8 +8,10 @@ redirects:
   - { from: 'index.xml', to: '2024/index.xml 302!' }
 outputs: [HTML, RSS]
 htmltest:
-  # 2024-11-07 DO NOT COPY the following IgnoreDirs to non-en pages because handles all locales.
+  # 2024-11-07 DO NOT COPY the following IgnoreDirs to non-en pages because it handles all locales.
   IgnoreDirs:
     # Ignore blog index pages for all locales and in all blog sections (top-level and years)
     - ^(../)?blog/(\d+/)?page/\d+
+    # Ignore old blog posts
+    - ^(../)?blog/20(19|21|22|23)/
 ---

content/en/docs/collector/architecture.md

@@ -83,7 +83,7 @@ service:
 ```
 
 The previous example defines a pipeline for the traces type of telemetry data,
-with three receivers, two processors, and three exporters.
+with two receivers, two processors, and two exporters.
 
 ### Receivers
 

content/en/docs/collector/internal-telemetry.md

@@ -122,7 +122,7 @@ journalctl | grep otelcol | grep Error
 {{% /tab %}} {{< /tabpane >}}
 
 The following configuration can be used to emit internal logs from the Collector
-to an OTLP/gRPC backend:
+to an OTLP/HTTP backend:
 
 ```yaml
 service:
@@ -132,7 +132,7 @@ service:
         - batch:
             exporter:
               otlp:
-                protocol: grpc/protobuf
+                protocol: http/protobuf
                 endpoint: https://backend:4317
 ```
 

content/en/docs/concepts/instrumentation/libraries.md

@@ -115,7 +115,7 @@ to help you decide how to minimize dependency conflicts:
 - While your instrumentation stabilizes, consider shipping it as a separate
   package, so that it never causes issues for users who don't use it. You can
   keep it in your repository, or
-  [add it to OpenTelemetry](https://github.com/open-telemetry/oteps/blob/main/text/0155-external-modules.md#contrib-components),
+  [add it to OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0155-external-modules.md#contrib-components),
   so it ships with other instrumentation libraries.
 - Semantic conventions are [stable, but subject to evolution][]: while this does
   not cause any functional issues, you might need to update your instrumentation

content/en/docs/concepts/signals/_index.md

@@ -20,7 +20,7 @@ OpenTelemetry currently supports [traces](/docs/concepts/signals/traces),
 [metrics](/docs/concepts/signals/metrics), [logs](/docs/concepts/signals/logs)
 and [baggage](/docs/concepts/signals/baggage). _Events_ are a specific type of
 log, and
-[_profiles_ are being worked on](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md)
+[_profiles_ are being worked on](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/profiles/0212-profiling-vision.md)
 by the Profiling Working Group.
 
 [signals]: /docs/specs/otel/glossary/#signals

content/en/docs/concepts/signals/traces.md

@@ -312,6 +312,9 @@ trace. Now, they are causally associated with one another.
 Links are optional but serve as a good way to associate trace spans with one
 another.
 
+For more information regarding Span Links, see
+[Link](/docs/specs/otel/trace/api/#link).
+
 ### Span Status
 
 Each span has a status. The three possible values are:

content/en/docs/demo/services/recommendation.md

@@ -8,7 +8,7 @@ cSpell:ignore: cpython instrumentor NOTSET
 This service is responsible to get a list of recommended products for the user
 based on existing product IDs the user is browsing.
 
-[Recommendation service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/recommendationservice/)
+[Recommendation service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/recommendation/)
 
 ## Auto-instrumentation
 

content/en/docs/languages/java/_index.md

@@ -6,7 +6,7 @@ description: >-
 aliases: [/java, /java/metrics, /java/tracing]
 cascade:
   vers:
-    instrumentation: 2.10.0
+    instrumentation: 2.11.0
     otel: 1.45.0
     contrib: 1.42.0
     semconv: 1.29.0

content/en/docs/languages/java/configuration.md

@@ -704,6 +704,6 @@ alone dictate SDK configuration. {{% /alert %}}
 
 For additional details, consult the following resources:
 
-- [Usage documentation](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/incubator#file-configuration)
-- [Example with Java agent](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent#file-configuration)
-- [Example without Java agent](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/file-configuration)
+- [Usage documentation](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/incubator#declarative-configuration)
+- [Example with Java agent](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent#declarative-configuration)
+- [Example without Java agent](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/declarative-configuration)

content/en/docs/languages/php/sdk.md

@@ -98,6 +98,14 @@ $meter = OpenTelemetry\API\Globals::meterProvider()->getMeter('name', 'version',
 
 SDK autoloading happens as part of the composer autoloader.
 
+### Configuration from php.ini
+
+When providing configuration through `php.ini`, be sure to protect boolean
+values by double-quoting them, eg `"true"`, `"false"` so that PHP doesn't
+convert them to numbers.
+
+`php.ini`:
+
 ### Excluded URLs
 
 You can disable SDK autoloading if the request URL matches a regular expression.
@@ -134,3 +142,13 @@ There are also a number of PHP-specific configurations:
 
 Configurations can be provided as environment variables, or via `php.ini` (or a
 file included by `php.ini`)
+
+{{% alert title="Boolean values in php.ini" %}} Boolean values in `php.ini`
+should be protected by double-quoting them, for example `"true"` or `"false"`,
+so that PHP doesn't convert them to numbers {{% /alert %}}
+
+```ini
+OTEL_PHP_AUTOLOAD_ENABLED="true"
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
+```

content/en/docs/zero-code/java/_index.md

@@ -6,7 +6,7 @@ aliases:
   - /docs/languages/java/automatic_instrumentation
 cascade:
   vers:
-    instrumentation: 2.10.0
+    instrumentation: 2.11.0
     otel: 1.45.0
 ---
 

content/en/docs/zero-code/java/agent/annotations.md

@@ -7,17 +7,18 @@ cSpell:ignore: Flowable javac reactivestreams reactivex
 ---
 
 For most users, the out-of-the-box instrumentation is completely sufficient and
-nothing more has to be done. Sometimes, however, users wish to create
+nothing more needs to be done. Sometimes, however, users wish to create
 [spans](/docs/concepts/signals/traces/#spans) for their own custom code without
-doing too much code change.
+having to change much code. The `WithSpan` and `WithAttribute` annotations
+support those use cases.
 
 ## Dependencies
 
 You'll need to add a dependency on the
 `opentelemetry-instrumentation-annotations` library to use the `@WithSpan`
 annotation.
 
-### Maven
+{{< tabpane text=true >}} {{% tab "Maven" %}}
 
 ```xml
 <dependencies>
@@ -29,6 +30,8 @@ annotation.
 </dependencies>
 ```
 
+{{% /tab %}} {{% tab "Gradle" %}}
+
 ### Gradle
 
 ```groovy
@@ -37,10 +40,12 @@ dependencies {
 }
 ```
 
+{{% /tab %}} {{< /tabpane >}}
+
 ## Creating spans around methods with `@WithSpan`
 
-To create a [span](/docs/concepts/signals/traces/#spans) corresponding to one of
-your method, annotate the method with `@WithSpan`.
+To create a [span](/docs/concepts/signals/traces/#spans) that instruments a
+particular method, annotate the method with `@WithSpan`.
 
 ```java
 import io.opentelemetry.instrumentation.annotations.WithSpan;
@@ -78,9 +83,10 @@ types listed below, then the span will not be ended until the future completes.
 ## Adding attributes to the span with `@SpanAttribute`
 
 When a [span](/docs/concepts/signals/traces/#spans) is created for an annotated
-method the values of the arguments to the method invocation can be automatically
-added as [attributes](/docs/concepts/signals/traces/#attributes) to the created
-span by annotating the method parameters with the `@SpanAttribute` annotation.
+method, the values of the arguments to the method invocation can be
+automatically added as [attributes](/docs/concepts/signals/traces/#attributes)
+to the created span. Simply annotate the method parameters with the
+`@SpanAttribute` annotation:
 
 ```java
 import io.opentelemetry.instrumentation.annotations.SpanAttribute;

content/en/docs/zero-code/java/agent/configuration.md

@@ -21,24 +21,24 @@ The agent can consume configuration from one or more of the following sources
 
 ## Configuring with Environment Variables
 
-In some environments, configuring via Environment Variables is more preferred.
-Any setting configurable with a System Property can also be configured with an
-Environment Variable. Many settings below include both options, but where they
-don't apply the following steps to determine the correct name mapping of the
-desired System Property:
+In certain environments, configuring settings through environment variables is
+often preferred. Any setting that can be configured using a system property can
+also be set using an environment variable. While many of the settings below
+provide examples for both formats, for those that do not, use the following
+steps to determine the correct name mapping for the desired system property:
 
-- Convert the System Property to uppercase.
+- Convert the system property name to uppercase.
 - Replace all `.` and `-` characters with `_`.
 
 For example `otel.instrumentation.common.default-enabled` would convert to
 `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`.
 
 ## Configuration file
 
-You can provide a path to agent configuration file by setting the following
+You can provide a path to an agent configuration file by setting the following
 property:
 
-{{% config_option name="otel.javaagent.configuration-file" %}} Path to valid
+{{% config_option name="otel.javaagent.configuration-file" %}} Path to a valid
 Java properties file which contains the agent configuration.
 {{% /config_option %}}
 

content/en/docs/zero-code/java/agent/disable.md

@@ -26,10 +26,11 @@ to have more control of which instrumentation is applied.
 {{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `true`
 to enable each desired instrumentation individually. {{% /config_option %}}
 
-> **Note**: Some instrumentation relies on other instrumentation to function
-> properly. When selectively enabling instrumentation, be sure to enable the
-> transitive dependencies too. Determining this dependency relationship is left
-> as an exercise to the user.
+{{% alert title="Note" color="warning" %}} Some instrumentation relies on other
+instrumentation to function properly. When selectively enabling instrumentation,
+be sure to enable the transitive dependencies too. Determining this dependency
+relationship is left as an exercise to the user. This is considered advanced
+usage and is not recommended for most users. {{% /alert %}}
 
 ## Enable manual instrumentation only