[extension/ballastextension] Deprecate memory_ballast extension (#8803)

**Description:** 

Based on user reports on
open-telemetry/opentelemetry-helm-charts/issues/891 and the discussion
on #8343, we can deprecate the memory ballast extension in favor of
using `GOMEMLIMIT`. This PR:

- Deprecates the memory ballast extension in the README
- Removes references to the memory ballast extension on docs
- Updates k8s example to use `GOMEMLIMIT` with the same approach as in
the Helm chart (80% of memory limit)
- Deprecates the memory ballast extension Go module

Once this PR is accepted,
open-telemetry/opentelemetry-helm-charts/issues/891 can move ahead with
enabling `useGOMEMLIMIT` by default on the Helm chart.

Other issues will be opened for opentelemetry.io, the Opentelemetry
Operator and other parts of the OpenTelemetry project to remove
references to this extension once the PR is merged.

No explicit timeline is given for removal of the extension.

**Link to tracking Issue:** Updates #8343

---------

Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com>

.chloggen/mx-psi_deprecate-memory-ballast.yaml

@@ -0,0 +1,26 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: extension/ballast
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Deprecate `memory_ballast` extension.
+
+# One or more tracking issues or pull requests related to the change
+issues: [8343]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: | 
+    Use `GOMEMLIMIT` environment variable instead.
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

confmap/provider/internal/configurablehttpprovider/testdata/otel-config.yaml

@@ -1,6 +1,4 @@
 extensions:
-  memory_ballast:
-    size_mib: 512
   zpages:
     endpoint: 0.0.0.0:55679
 
@@ -34,4 +32,4 @@ service:
       processors: [memory_limiter, batch]
       exporters: [debug]
 
-  extensions: [memory_ballast, zpages]
+  extensions: [zpages]

examples/k8s/otel-config.yaml

@@ -35,11 +35,8 @@ data:
         check_interval: 5s
     extensions:
       zpages: {}
-      memory_ballast:
-        # Memory Ballast size should be max 1/3 to 1/2 of memory.
-        size_mib: 165
     service:
-      extensions: [zpages, memory_ballast]
+      extensions: [zpages]
       pipelines:
         traces:
           receivers: [otlp]
@@ -87,6 +84,8 @@ spec:
               fieldRef:
                 apiVersion: v1
                 fieldPath: status.podIP
+          - name: GOMEMLIMIT
+            value: 400MiB
         volumeMounts:
         - name: otel-agent-config-vol
           mountPath: /conf
@@ -124,16 +123,13 @@ data:
         check_interval: 5s
     extensions:
       zpages: {}
-      memory_ballast:
-        # Memory Ballast size should be max 1/3 to 1/2 of memory.
-        size_mib: 683
     exporters:
       otlp:
         endpoint: "http://someotlp.target.com:4317" # Replace with a real endpoint.
         tls:
           insecure: true
     service:
-      extensions: [zpages, memory_ballast]
+      extensions: [zpages]
       pipelines:
         traces/1:
           receivers: [otlp]
@@ -209,6 +205,8 @@ spec:
               fieldRef:
                 apiVersion: v1
                 fieldPath: status.podIP
+          - name: GOMEMLIMIT
+              value: 1600MiB
         volumeMounts:
         - name: otel-collector-config-vol
           mountPath: /conf

examples/local/otel-config.yaml

@@ -1,6 +1,4 @@
 extensions:
-  memory_ballast:
-    size_mib: 512
   zpages:
     endpoint: localhost:55679
 
@@ -36,4 +34,4 @@ service:
       processors: [memory_limiter, batch]
       exporters: [debug]
 
-  extensions: [memory_ballast, zpages]
+  extensions: [zpages]

extension/ballastextension/README.md

@@ -1,8 +1,16 @@
+> [!WARNING]
+> The memory ballast extension is deprecated in favor of using the `GOMEMLIMIT` environment variable.
+> This environment variable is available on any Collector built with Go 1.19 or higher. Official binary releases are built with Go 1.19 since v0.61.0. See [issue 8343](https://github.com/open-telemetry/opentelemetry-collector/issues/8343) for the deprecation timeline.
+> 
+> To migrate to  `GOMEMLIMIT`, set its value to 80% of the hard memory limit of your Collector. 
+> For example, if the Collector hard memory limit is 1GiB, set `GOMEMLIMIT` to `800MiB`.
+> Check [the Go documentation](https://pkg.go.dev/runtime#hdr-Environment_Variables) for more information about `GOMEMLIMIT`'s syntax.
+
 # Memory Ballast
 
 | Status                   |                   |
 | ------------------------ | ----------------- |
-| Stability                | [beta]            |
+| Stability                | [deprecated]      |
 | Distributions            | [core], [contrib] |
 
 Memory Ballast extension enables applications to configure memory ballast for the process. For more details see:
@@ -47,6 +55,6 @@ extensions:
     size_in_percentage: 20
 ```
 
-[beta]: https://github.com/open-telemetry/opentelemetry-collector-contrib#beta
+[deprecated]: https://github.com/open-telemetry/opentelemetry-collector-contrib#deprecated
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
 [core]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol

extension/ballastextension/factory.go

@@ -21,7 +21,7 @@ var memHandler = iruntime.TotalMemory
 
 // NewFactory creates a factory for FluentBit extension.
 func NewFactory() extension.Factory {
-	return extension.NewFactory(typeStr, createDefaultConfig, createExtension, component.StabilityLevelBeta)
+	return extension.NewFactory(typeStr, createDefaultConfig, createExtension, component.StabilityLevelDeprecated)
 }
 
 func createDefaultConfig() component.Config {

extension/ballastextension/go.mod

@@ -1,3 +1,4 @@
+// Deprecated: Use the GOMEMLIMIT environment variable instead.
 module go.opentelemetry.io/collector/extension/ballastextension
 
 go 1.20

service/README.md

@@ -142,7 +142,6 @@ exporters:
    - debug
 extensions:
    - zpages
-   - memory_ballast
 ```
 
 ## How to validate configuration file and return all errors without running collector