Skip to main content

Quick start

This page takes you from a new ingestion stream to a delivered object. It assumes you have a bucket or table to write to.

1. Create an ingestion stream​

Sign in to the dashboard and create an ingestion stream. Copy the API key when it is shown: it is displayed once, and afterwards the dashboard shows only its first 14 characters.

export S2B_API_KEY=s2b_ingest_...

2. Connect and verify the destination​

Choose one destination for the stream and follow its page under Destinations. During setup Send2Bucket checks access before the stream accepts data:

  • Buckets: it writes a test object under your prefix and reads it back.
  • Tables: it creates the table in the namespace you name if it is missing, or checks the existing table's columns, and checks write permissions.

Until the destination is verified, requests get 409 destination_not_ready.

3. Send a JSON event​

Send one object or an array of objects to /v1/events:

curl https://api.s2b.tznc.dev/v1/events \
-H "Authorization: Bearer $S2B_API_KEY" \
-H "Content-Type: application/json" \
-d '[{"event":"order.paid","order_id":"ord_20931","cents":4200},
{"event":"email.sent","order_id":"ord_20931"}]'

The 200 response comes after the batch is stored durably:

{"accepted":2,"bytes":106}

bytes is the length of the decompressed request body. It is the number billed.

4. Find the records​

Batches are delivered at least every 60 seconds. The records then appear under <prefix>/s2b/stream=<stream_id>/date=<YYYY-MM-DD>/hour=<HH>/ in your bucket, one gzip NDJSON object per delivery, or as rows in your table. Each record carries the batch_id of the request that sent it; see the delivery format.

5. Send OpenTelemetry data​

Send2Bucket accepts OTLP over HTTP with protobuf encoding and over gRPC. Both use the same API key.

OpenTelemetry Collector, OTLP/HTTP​

The otlphttp exporter appends /v1/logs, /v1/traces and /v1/metrics to the endpoint.

exporters:
otlphttp/s2b:
endpoint: https://api.s2b.tznc.dev
headers:
authorization: Bearer ${env:S2B_API_KEY}
compression: gzip

service:
pipelines:
logs:
receivers: [otlp]
exporters: [otlphttp/s2b]
traces:
receivers: [otlp]
exporters: [otlphttp/s2b]
metrics:
receivers: [otlp]
exporters: [otlphttp/s2b]

OpenTelemetry Collector, OTLP/gRPC​

The otlp exporter connects over TLS and HTTP/2 to port 443 and sends the key as authorization metadata.

exporters:
otlp/s2b:
endpoint: api.s2b.tznc.dev:443
headers:
authorization: Bearer ${env:S2B_API_KEY}
compression: gzip

Reference otlp/s2b in the pipelines the same way as above.

SDK exporters​

Most OpenTelemetry SDKs read these variables. The space after Bearer is percent-encoded, as the specification requires for header values.

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.s2b.tznc.dev
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20$S2B_API_KEY"

Next​