[extension/pebbletailstorage] Promote pebble_tail_storage extension to alpha stability (#48877)

#### Description

Promote pebble tail storage extension to alpha stability

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #47916
Fixes #42326

<!--Describe what testing was performed and which tests were added.-->
#### Testing

<!--Describe the documentation added.-->
#### Documentation

<!--Authorship attestation. See AGENTS.md for details. AI agents must
not check this box on behalf
of the user; the human author must check it themselves before the PR is
ready for review.-->
#### Authorship

- [x] I, a human, wrote this pull request description myself.

<!--Please delete paragraphs that you did not use before submitting.-->

Author: carsonip

.chloggen/pebbletailstorageextension-alpha.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: extension/pebble_tail_storage
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Promote `pebble_tail_storage` extension to alpha stability
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [47916]
+
+# (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:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# 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: [user]

cmd/otelcontribcol/builder-config.yaml

@@ -45,6 +45,7 @@ extensions:
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/dbstorage v0.153.0
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/filestorage v0.153.0
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/redisstorageextension v0.153.0
+  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/tailstorage/pebbletailstorageextension v0.153.0
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/sumologicextension v0.153.0
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/awscloudwatchmetricstreamsencodingextension v0.153.0
   - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/awslogsencodingextension v0.153.0

extension/tailstorage/pebbletailstorageextension/README.md

@@ -5,13 +5,14 @@ Stores pending trace data for tail sampling in a local Pebble database.
 
 | Status        |           |
 | ------------- |-----------|
-| Stability     | [development]  |
-| Distributions | [] |
+| Stability     | [alpha]  |
+| Distributions | [contrib] |
 | Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Aextension%2Fpebbletailstorage%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Aextension%2Fpebbletailstorage) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Aextension%2Fpebbletailstorage%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Aextension%2Fpebbletailstorage) |
 | Code coverage | [![codecov](https://codecov.io/github/open-telemetry/opentelemetry-collector-contrib/graph/main/badge.svg?component=extension_pebbletailstorage)](https://app.codecov.io/gh/open-telemetry/opentelemetry-collector-contrib/tree/main/?components%5B0%5D=extension_pebbletailstorage&displayType=list) |
 | [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@carsonip](https://www.github.com/carsonip), [@jmacd](https://www.github.com/jmacd), [@axw](https://www.github.com/axw) |
 
-[development]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#development
+[alpha]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#alpha
+[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
 <!-- end autogenerated section -->
 
 # Pebble Tail Storage Extension
@@ -22,10 +23,6 @@ Tail Sampling processor.
 This extension is intended to be used with the Tail Sampling processor `tail_storage`
 setting and is useful when in-memory pending-trace state would otherwise be too large.
 
-## Status
-
-This extension is in development and may change.
-
 ## Limitations
 
 Persistence across collector restarts is **not yet supported**. The extension
@@ -39,17 +36,40 @@ treat the directory as ephemeral.
 
 ## Example
 
+The following example uses the `span-ingest` sampling strategy with a decision
+cache and Pebble tail storage. The `span-ingest` strategy evaluates each
+incoming span batch immediately on ingest, which avoids accumulating complete
+traces in memory before making a decision. Combined with `tail_storage`, spans
+for traces that are still pending a decision are written to disk rather than
+held in memory, keeping collector memory usage bounded under high load.
+
+The `decision_cache` keeps a record of already-decided trace IDs so that late
+spans for sampled or dropped traces are handled correctly without re-evaluating
+policies.
+
 ```yaml
 extensions:
   pebble_tail_storage:
     directory: /var/lib/otelcol/pebble-tail-storage
 
+receivers:
+  otlp:
+    protocols:
+      grpc:
+
+exporters:
+  debug:
+
 processors:
   tail_sampling:
-    decision_wait: 30s
+    sampling_strategy: span-ingest
+    decision_wait: 2m
     num_traces: 50000
     expected_new_traces_per_sec: 1000
     tail_storage: pebble_tail_storage
+    decision_cache:
+      sampled_cache_size: 100000
+      non_sampled_cache_size: 100000
     policies:
       - name: errors
         type: status_code

extension/tailstorage/pebbletailstorageextension/go.mod

@@ -22,13 +22,13 @@ require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cockroachdb/crlib v0.0.0-20241112164430-1264a2edc35b // indirect
-	github.com/cockroachdb/errors v1.11.3 // indirect
+	github.com/cockroachdb/errors v1.13.0 // indirect
 	github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect
 	github.com/cockroachdb/redact v1.1.5 // indirect
 	github.com/cockroachdb/swiss v0.0.0-20251224182025-b0f6560f979b // indirect
 	github.com/cockroachdb/tokenbucket v0.0.0-20230807174530-cc333fc44b06 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
-	github.com/getsentry/sentry-go v0.27.0 // indirect
+	github.com/getsentry/sentry-go v0.46.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect

extension/tailstorage/pebbletailstorageextension/go.sum

@@ -38,7 +38,7 @@ require (
 	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cockroachdb/crlib v0.0.0-20241112164430-1264a2edc35b // indirect
-	github.com/cockroachdb/errors v1.11.3 // indirect
+	github.com/cockroachdb/errors v1.13.0 // indirect
 	github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect
 	github.com/cockroachdb/pebble/v2 v2.1.6 // indirect
 	github.com/cockroachdb/redact v1.1.5 // indirect
@@ -51,7 +51,7 @@ require (
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/foxboron/go-tpm-keyfiles v0.0.0-20251226215517-609e4778396f // indirect
 	github.com/fsnotify/fsnotify v1.10.1 // indirect
-	github.com/getsentry/sentry-go v0.27.0 // indirect
+	github.com/getsentry/sentry-go v0.46.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect

extension/tailstorage/pebbletailstorageextension/integrationtest/go.mod

@@ -6,7 +6,7 @@ description: Stores pending trace data for tail sampling in a local Pebble datab
 status:
   class: extension
   stability:
-    development: [extension]
-  distributions: []
+    alpha: [extension]
+  distributions: [contrib]
   codeowners:
     active: [carsonip, jmacd, axw]

extension/tailstorage/pebbletailstorageextension/integrationtest/go.sum

@@ -93,6 +93,7 @@ components:
         - oidc
         - opamp
         - otlp_encoding
+        - pebble_tail_storage
         - pprof
         - redis_storage
         - sigv4auth