feat: optionally export sampled traces to a GCS bucket

app/app_test.go

@@ -368,6 +368,7 @@ func newStartedApp(
 		&inject.Object{Value: http.DefaultTransport, Name: "upstreamTransport"},
 		&inject.Object{Value: upstreamTransmission, Name: "upstreamTransmission"},
 		&inject.Object{Value: peerTransmissionWrapper, Name: "peerTransmission"},
+		&inject.Object{Value: &transmit.NoopTransmission{}, Name: "gcsExport"},
 		&inject.Object{Value: shrdr},
 		&inject.Object{Value: noop.NewTracerProvider().Tracer("test"), Name: "tracer"},
 		&inject.Object{Value: collector},

cmd/refinery/main.go

@@ -186,6 +186,13 @@ func main() {
 		nil, // No custom headers for peer-to-peer traffic
 	)
 
+	// the GCS exporter is optional; when it's disabled we inject a noop so
+	// that the collector's dependency is always satisfied
+	var gcsExport transmit.Transmission = &transmit.NoopTransmission{}
+	if c.GetGCSExportConfig().Enabled {
+		gcsExport = transmit.NewGCSTransmission()
+	}
+
 	// we need to include all the metrics types so we can inject them in case they're needed
 	// but we only want to instantiate the ones that are enabled with non-null values
 	var promMetrics metrics.MetricsBackend = &metrics.NullMetrics{}
@@ -241,6 +248,7 @@ func main() {
 		{Value: peerTransport, Name: "peerTransport"},
 		{Value: upstreamTransmission, Name: "upstreamTransmission"},
 		{Value: peerTransmission, Name: "peerTransmission"},
+		{Value: gcsExport, Name: "gcsExport"},
 		{Value: shrdr},
 		{Value: collector},
 		{Value: promMetrics, Name: "promMetrics"},

collect/collect.go

@@ -88,6 +88,7 @@ type InMemCollector struct {
 
 	Transmission     transmit.Transmission  `inject:"upstreamTransmission"`
 	PeerTransmission transmit.Transmission  `inject:"peerTransmission"`
+	GCSExport        transmit.Transmission  `inject:"gcsExport"`
 	PubSub           pubsub.PubSub          `inject:""`
 	Metrics          metrics.Metrics        `inject:"metrics"`
 	SamplerFactory   *sample.SamplerFactory `inject:""`
@@ -491,10 +492,20 @@ func (i *InMemCollector) ProcessSpanImmediately(sp *types.Span) (processed bool,
 	i.addAdditionalAttributes(sp)
 	mergeTraceAndSpanSampleRates(sp, rate, i.Config.GetIsDryRun())
 	i.Transmission.EnqueueSpan(sp)
+	i.exportSpan(sp)
 
 	return true, true
 }
 
+// exportSpan sends a kept span to the optional GCS exporter, if one is
+// configured. It must only be called for spans of traces that were actually
+// kept by the sampler (not for dry-run "would have dropped" sends).
+func (i *InMemCollector) exportSpan(sp *types.Span) {
+	if i.GCSExport != nil {
+		i.GCSExport.EnqueueSpan(sp)
+	}
+}
+
 // dealWithSentTrace handles a span that has arrived after the sampling decision
 // on the trace has already been made, and it obeys that decision by either
 // sending the span immediately or dropping it.
@@ -557,6 +568,7 @@ func (i *InMemCollector) dealWithSentTrace(ctx context.Context, tr cache.TraceSe
 		i.Metrics.Increment(TraceSendLateSpan)
 		i.addAdditionalAttributes(sp)
 		i.Transmission.EnqueueSpan(sp)
+		i.exportSpan(sp)
 		return
 	}
 	i.Metrics.Increment("events_dropped")
@@ -834,6 +846,12 @@ func (i *InMemCollector) sendTraces() {
 
 			sp.APIKey = t.APIKey
 			i.Transmission.EnqueueSpan(sp)
+			// only export spans of traces the sampler actually kept; in dry
+			// run mode, traces that would have been dropped still reach here
+			// with shouldSend=false and are not exported.
+			if t.shouldSend {
+				i.exportSpan(sp)
+			}
 		}
 		span.End()
 	}

collect/collect_test.go

@@ -882,6 +882,7 @@ func TestDependencyInjection(t *testing.T) {
 		&inject.Object{Value: &sharder.SingleServerSharder{}},
 		&inject.Object{Value: &transmit.MockTransmission{}, Name: "upstreamTransmission"},
 		&inject.Object{Value: &transmit.MockTransmission{}, Name: "peerTransmission"},
+		&inject.Object{Value: &transmit.NoopTransmission{}, Name: "gcsExport"},
 		&inject.Object{Value: &pubsub.LocalPubSub{}},
 		&inject.Object{Value: &metrics.NullMetrics{}, Name: "metrics"},
 		&inject.Object{Value: &sample.SamplerFactory{}},

config.md

@@ -3,7 +3,7 @@
 # Honeycomb Refinery Configuration Documentation
 
 This is the documentation for the configuration file for Honeycomb's Refinery.
-It was automatically generated on 2026-04-09 at 22:21:32 UTC.
+It was automatically generated on 2026-07-07 at 21:27:51 UTC.
 
 ## The Config file
 
@@ -48,6 +48,7 @@ The remainder of this document describes the sections within the file and the fi
 - [gRPC Server Parameters](#grpc-server-parameters)
 - [Sample Cache](#sample-cache)
 - [Stress Relief](#stress-relief)
+- [GCS Export](#gcs-export)
 ## General Configuration
 
 `General` contains general configuration options that apply to the entire Refinery process.
@@ -1315,3 +1316,74 @@ This setting helps to prevent oscillations.
 - Type: `duration`
 - Default: `10s`
 
+## GCS Export
+
+`GCSExport` contains configuration for optionally exporting sampled (kept) trace spans to a Google Cloud Storage bucket in addition to sending them to Honeycomb.
+Spans are buffered in memory and written as gzipped JSON Lines objects, batched into time-partitioned paths of the form `KeyPrefix/YYYY/MM/DD/HH/hostname-timestamp.jsonl.gz`.
+Authentication uses Google Application Default Credentials.
+
+### `Enabled`
+
+Enabled controls whether kept trace spans are also exported to a GCS bucket.
+
+If `true`, every span belonging to a trace that Refinery decides to keep is also written to the configured GCS bucket.
+Spans of dropped traces are never exported.
+
+- Not eligible for live reload.
+- Type: `bool`
+
+### `Bucket`
+
+Bucket is the name of the GCS bucket to which sampled traces are exported.
+
+The bucket must already exist and the credentials available via Application Default Credentials must have permission to create objects in it.
+Required when `Enabled` is `true`.
+
+- Not eligible for live reload.
+- Type: `string`
+- Example: `my-trace-archive`
+- Environment variable: `REFINERY_GCS_EXPORT_BUCKET`
+
+### `KeyPrefix`
+
+KeyPrefix is the object name prefix under which exported objects are written.
+
+Object names are formed by appending time-partitioned path elements to this prefix.
+Leave empty to write at the root of the bucket.
+
+- Not eligible for live reload.
+- Type: `string`
+- Example: `refinery/traces`
+
+### `FlushInterval`
+
+FlushInterval is the maximum time a batch of spans is buffered before being written to GCS.
+
+A batch is flushed to GCS when it reaches `MaxBatchSize` or when this interval has elapsed since the batch was started, whichever comes first.
+
+- Not eligible for live reload.
+- Type: `duration`
+- Default: `60s`
+
+### `MaxBatchSize`
+
+MaxBatchSize is the maximum uncompressed size of a batch before it is written to GCS.
+
+When the serialized (uncompressed) size of the current batch exceeds this value, it is compressed and written to GCS immediately.
+The objects stored in GCS are gzip-compressed and thus considerably smaller than this value.
+
+- Not eligible for live reload.
+- Type: `memorysize`
+- Default: `100MB`
+
+### `QueueSize`
+
+QueueSize is the number of spans that can be queued for export before spans are dropped.
+
+Spans are handed to the exporter through a fixed-size queue so that a slow or unavailable GCS never blocks sending traces to Honeycomb.
+If the queue is full, new spans are dropped from the export (they are still sent to Honeycomb) and the `gcs_export_dropped` metric is incremented.
+
+- Not eligible for live reload.
+- Type: `int`
+- Default: `100000`
+

config/cmdenv.go

@@ -48,6 +48,7 @@ type CmdEnv struct {
 	QueryAuthToken                      string            `long:"query-auth-token" env:"REFINERY_QUERY_AUTH_TOKEN" description:"Token for debug/management queries. Setting this value via a flag may expose credentials - it is recommended to use the env var or a configuration file."`
 	AvailableMemory                     MemorySize        `long:"available-memory" env:"REFINERY_AVAILABLE_MEMORY" description:"The maximum memory available for Refinery to use (ex: 4GiB)."`
 	SendKey                             string            `long:"send-key" env:"REFINERY_SEND_KEY" description:"The Honeycomb API key that Refinery can use to send data to Honeycomb."`
+	GCSExportBucket                     string            `long:"gcs-export-bucket" env:"REFINERY_GCS_EXPORT_BUCKET" description:"Name of the GCS bucket to export sampled traces to (when GCSExport is enabled)."`
 	Debug                               bool              `short:"d" long:"debug" description:"Runs debug service (on the first open port between localhost:6060 and :6069 by default)"`
 	Version                             bool              `short:"v" long:"version" description:"Print version number and exit"`
 	InterfaceNames                      bool              `long:"interface-names" description:"Print system's network interface names and exit."`

config/config.go

@@ -122,6 +122,9 @@ type Config interface {
 
 	GetOTelTracingConfig() OTelTracingConfig
 
+	// GetGCSExportConfig returns the config specific to GCSExport
+	GetGCSExportConfig() GCSExportConfig
+
 	GetUseIPV6Identifier() bool
 
 	GetRedisIdentifier() string

config/config_serializer.go

@@ -75,6 +75,7 @@ func populateConfigContents(cfg Config) configContents {
 		GRPCServerParameters: cfg.GetGRPCConfig(),
 		SampleCache:          cfg.GetSampleCacheConfig(),
 		StressRelief:         cfg.GetStressReliefConfig(),
+		GCSExport:            cfg.GetGCSExportConfig(),
 	}
 }
 

config/file_config.go

@@ -67,6 +67,7 @@ type configContents struct {
 	GRPCServerParameters GRPCServerParameters      `yaml:"GRPCServerParameters"`
 	SampleCache          SampleCacheConfig         `yaml:"SampleCache"`
 	StressRelief         StressReliefConfig        `yaml:"StressRelief"`
+	GCSExport            GCSExportConfig           `yaml:"GCSExport"`
 }
 
 type GeneralConfig struct {
@@ -287,6 +288,17 @@ type OTelMetricsConfig struct {
 	AdditionalAttributes map[string]string `yaml:"AdditionalAttributes" default:"{}" cmdenv:"OTelMetricsAdditionalAttributes"`
 }
 
+// GCSExportConfig configures the optional export of sampled (kept) trace
+// spans to a Google Cloud Storage bucket as gzipped JSON Lines objects.
+type GCSExportConfig struct {
+	Enabled       bool       `yaml:"Enabled" default:"false"`
+	Bucket        string     `yaml:"Bucket" cmdenv:"GCSExportBucket"`
+	KeyPrefix     string     `yaml:"KeyPrefix"`
+	FlushInterval Duration   `yaml:"FlushInterval" default:"60s"`
+	MaxBatchSize  MemorySize `yaml:"MaxBatchSize" default:"100MB"`
+	QueueSize     int        `yaml:"QueueSize" default:"100000"`
+}
+
 type OTelTracingConfig struct {
 	Enabled    bool   `yaml:"Enabled" default:"false"`
 	APIHost    string `yaml:"APIHost" default:"https://api.honeycomb.io" cmdenv:"TelemetryEndpoint"`
@@ -1027,6 +1039,13 @@ func (f *fileConfig) GetOTelMetricsConfig() OTelMetricsConfig {
 	return f.mainConfig.OTelMetrics
 }
 
+func (f *fileConfig) GetGCSExportConfig() GCSExportConfig {
+	f.mux.RLock()
+	defer f.mux.RUnlock()
+
+	return f.mainConfig.GCSExport
+}
+
 func (f *fileConfig) GetDebugServiceAddr() string {
 	f.mux.RLock()
 	defer f.mux.RUnlock()

config/metadata/configMeta.yaml

@@ -2123,3 +2123,91 @@ groups:
           If this duration is `0`, then Refinery will not start in stressed
           mode, which will provide faster startup at the possible cost of
           startup instability.
+
+  - name: GCSExport
+    title: "GCS Export"
+    description: >
+      contains configuration for optionally exporting sampled (kept) trace
+      spans to a Google Cloud Storage bucket in addition to sending them to
+      Honeycomb. Spans are buffered in memory and written as gzipped JSON
+      Lines objects, batched into time-partitioned paths of the form
+      `KeyPrefix/YYYY/MM/DD/HH/hostname-timestamp.jsonl.gz`. Authentication
+      uses Google Application Default Credentials.
+    fields:
+      - name: Enabled
+        type: bool
+        valuetype: nondefault
+        firstversion: v3.3
+        default: false
+        reload: false
+        summary: controls whether kept trace spans are also exported to a GCS bucket.
+        description: >
+          If `true`, every span belonging to a trace that Refinery decides to
+          keep is also written to the configured GCS bucket. Spans of dropped
+          traces are never exported.
+
+      - name: Bucket
+        type: string
+        valuetype: nondefault
+        firstversion: v3.3
+        default: ""
+        example: "my-trace-archive"
+        envvar: REFINERY_GCS_EXPORT_BUCKET
+        commandline: gcs-export-bucket
+        reload: false
+        summary: is the name of the GCS bucket to which sampled traces are exported.
+        description: >
+          The bucket must already exist and the credentials available via
+          Application Default Credentials must have permission to create
+          objects in it. Required when `Enabled` is `true`.
+
+      - name: KeyPrefix
+        type: string
+        valuetype: nondefault
+        firstversion: v3.3
+        default: ""
+        example: "refinery/traces"
+        reload: false
+        summary: is the object name prefix under which exported objects are written.
+        description: >
+          Object names are formed by appending time-partitioned path elements
+          to this prefix. Leave empty to write at the root of the bucket.
+
+      - name: FlushInterval
+        type: duration
+        valuetype: nondefault
+        firstversion: v3.3
+        default: 60s
+        reload: false
+        summary: is the maximum time a batch of spans is buffered before being written to GCS.
+        description: >
+          A batch is flushed to GCS when it reaches `MaxBatchSize` or when
+          this interval has elapsed since the batch was started, whichever
+          comes first.
+
+      - name: MaxBatchSize
+        type: memorysize
+        valuetype: memorysize
+        firstversion: v3.3
+        default: 100MB
+        reload: false
+        summary: is the maximum uncompressed size of a batch before it is written to GCS.
+        description: >
+          When the serialized (uncompressed) size of the current batch exceeds
+          this value, it is compressed and written to GCS immediately. The
+          objects stored in GCS are gzip-compressed and thus considerably
+          smaller than this value.
+
+      - name: QueueSize
+        type: int
+        valuetype: nondefault
+        firstversion: v3.3
+        default: 100000
+        reload: false
+        summary: is the number of spans that can be queued for export before spans are dropped.
+        description: >
+          Spans are handed to the exporter through a fixed-size queue so that
+          a slow or unavailable GCS never blocks sending traces to Honeycomb.
+          If the queue is full, new spans are dropped from the export (they
+          are still sent to Honeycomb) and the `gcs_export_dropped` metric is
+          incremented.

config/mock.go

@@ -36,6 +36,7 @@ type MockConfig struct {
 	GetOpAmpConfigVal                OpAMPConfig
 	GetOTelMetricsConfigVal          OTelMetricsConfig
 	GetOTelTracingConfigVal          OTelTracingConfig
+	GetGCSExportConfigVal            GCSExportConfig
 	IdentifierInterfaceName          string
 	UseIPV6Identifier                bool
 	RedisIdentifier                  string
@@ -251,6 +252,13 @@ func (m *MockConfig) GetOTelTracingConfig() OTelTracingConfig {
 	return m.GetOTelTracingConfigVal
 }
 
+func (m *MockConfig) GetGCSExportConfig() GCSExportConfig {
+	m.Mux.RLock()
+	defer m.Mux.RUnlock()
+
+	return m.GetGCSExportConfigVal
+}
+
 // GetSamplerConfigForDestName returns the sampler config for the given dataset/environment.
 // If Samplers map is populated, it will look up the dataset-specific config.
 // Falls back to GetSamplerTypeVal if Samplers is not set (backwards compatible).