Skip to content

Vocabulary

What each Amazon SQS, Lambda, OpenTelemetry and Trailbeam term means in these docs.

Based on 7 repo files at 54ea61b

docs/glossary.md, docs/span-contract.md, docs/architecture.md, docs/store-api.md, python/src/trailbeam/boto.py, node/src/sqs.js, server/src/trailbeam_store/timeline.py

On this page

Each term here has one meaning across the Trailbeam docs. Amazon SQS and OpenTelemetry terms keep the meaning AWS and OpenTelemetry give them; Trailbeam adds a few of its own, listed last.

Amazon SQS#

Term Meaning
Queue Where producers put messages and consumers receive them. A standard queue delivers each message at least once, in roughly the order sent. A FIFO queue keeps order within a message group and removes duplicates. Trailbeam 0.1 is tested on standard queues only.
Message One item in a queue: a body plus attributes. It stays in the queue until a consumer deletes it or the retention period runs out.
Message ID MessageId, assigned by SQS when the message is sent. It stays the same on every receive, including a receive from a dead-letter queue. Trailbeam joins everything about a message by this ID.
Producer Any code that sends messages (SendMessage or SendMessageBatch).
Consumer Any code that receives messages (ReceiveMessage) and then deletes them. A Lambda function behind an event source mapping is a consumer too.
Handler In AWS Lambda, the function Lambda invokes with a batch of records; the Trailbeam wrapper wraps it. These docs use the word only for Lambda. Outside Lambda, Trailbeam sees your SQS calls, never the code that processes a message, so the docs say consumer for who did something and processing for the work.
Receive One ReceiveMessage call returning a message. A receive does not remove the message; it starts its visibility timeout.
Receipt handle A token SQS returns with each receive of a message. You need it to delete the message or change its visibility. It is different on every receive, so it identifies one delivery, not the message.
Visibility timeout How long a message stays not visible after a receive. The default is 30 seconds and the maximum is 12 hours. If the message is not deleted before it expires, it becomes visible again and can be received again.
Visible Available to be returned by a ReceiveMessage call.
In flight Received, not yet deleted, and still inside its visibility timeout.
Change visibility ChangeMessageVisibility: sets a new visibility timeout on an in-flight message, counted from the call. A value of 0 makes it visible at once.
Delete DeleteMessage, made with a receipt handle. This is the only way a consumer removes a message. With the handle of an older receive, the call can still succeed while the message is received again.
Receive count ApproximateReceiveCount: how many times SQS has returned the message. It goes up by one on every receive.
Dead-letter queue (DLQ) A queue that takes messages another queue could not get processed.
Redrive policy The setting on a source queue that names its dead-letter queue and its maxReceiveCount.
maxReceiveCount When a message's receive count goes past this number, SQS moves it to the dead-letter queue instead of returning it again.
DeadLetterQueueSourceArn A system attribute on a message received from a dead-letter queue, naming the queue it was moved from. This is how Trailbeam knows a move happened.
SentTimestamp When SQS accepted the message, in milliseconds, on SQS's clock.
ApproximateFirstReceiveTimestamp When SQS first returned the message, in milliseconds, on SQS's clock.
Long polling A ReceiveMessage with WaitTimeSeconds above 0, which waits up to that long for a message instead of returning empty at once.
Retention period How long SQS keeps a message that nobody deletes: 4 days by default, up to 14.

AWS Lambda#

Term Meaning
Event source mapping The Lambda feature that polls an SQS queue and invokes your function with a batch of messages. It does the receive and the delete for you.
Record One message inside the batch Lambda passes to your handler. It carries the message ID, receipt handle and attributes.
Function timeout How long one invocation may run. When it runs out, Lambda stops the invocation and logs Task timed out after N seconds.
Batch item failures With ReportBatchItemFailures turned on, your handler can return the IDs of the records that failed. Lambda deletes the rest and leaves those to become visible again. Without it, any error fails the whole batch.
Request ID The ID of one invocation, in the function's logs and in the Lambda context object.

OpenTelemetry#

Term Meaning
Span A record of one operation, with a start time, an end time, a name and attributes. Trailbeam writes one span per message per SQS call.
Trace The spans that share a trace ID, usually one request through several services. Trailbeam doesn't rely on traces; it joins spans by message ID instead.
Attribute A key and value on a span, such as messaging.message.id.
Instrumentation scope The name of the library that made a span. Trailbeam's spans have the scope trailbeam.
OTLP The OpenTelemetry protocol for sending spans. Trailbeam sends OTLP over HTTP.
Collector The OpenTelemetry Collector, a separate process that receives, filters and forwards spans. Optional with Trailbeam.
Sampling Dropping some traces to save cost. A sampler that drops Trailbeam spans leaves gaps in timelines; see Keep SQS spans when sampling.

Trailbeam#

Term Meaning
Hooks The code inside your services that turns SQS calls into Trailbeam spans: the boto3 hooks (trailbeam.boto.install()), the AWS SDK v3 middleware (trailbeam.instrument(client)) and the Lambda wrapper.
Lambda wrapper trailbeam.aws_lambda.wrap (Python) or trailbeam.wrapHandler (Node.js), around a handler invoked by an event source mapping.
Trailbeam span A span with instrumentation scope trailbeam. Trailbeam reads only these.
Settle span A trailbeam delete or trailbeam change_visibility span: a call that settles what happens to an in-flight message.
Server The process you run, started with trailbeam-store. It receives spans over OTLP/HTTP, keeps them in SQLite, and serves the JSON API and the web screen on one port.
Timeline Everything Trailbeam knows happened to one message ID, built by Trailbeam each time you ask for it. See Reading a timeline.
Step One entry in a timeline. The JSON API calls it an event.
Delivery One receive of a message, numbered 1, 2, 3 in order. Each delivery has its own receipt handle.
Final delete A delete SQS accepted, made with the receipt handle of the message's latest receive.
Recorded (observed) A step backed by a Trailbeam span, or a dead-letter move SQS reported. In the API, inferred: false.
Inferred A step Trailbeam worked out from the steps around it, with no span behind it. It has a window, never a time. In the API, inferred: true. See Recorded and inferred steps.
Concurrent group Steps that no recorded fact can put in order. The screen shows them in one dashed box labelled "concurrent, order unknown".
Order source The fact that proves one step came before another: the hosts' clocks, call order in one process, the receive count, or SQS's own timestamps. See How steps are ordered.
Call-order counter A counter in each Python process, or each Node.js realm, that ticks before every SQS request (trailbeam.order.issued) and after every response (trailbeam.order.returned). trailbeam.order.scope names the counter.
Receipt-handle hash An HMAC of the receipt handle, written instead of the handle itself, so Trailbeam can match a delete to its receive without seeing the token. See Receipt-handle hashing.
Receipt-hash key The secret key for that hash, set with TRAILBEAM_RECEIPT_HASH_KEY. Every service on the same queues must use the same key.