Implementation:Langfuse Langfuse S3 Slowdown Tracking

Knowledge Sources	Langfuse
Domains	Rate Limiting, Redis, S3 Storage
Last Updated	2026-02-14 00:00 GMT

Overview

Redis-backed utility for detecting, marking, and querying S3 SlowDown (rate limiting) errors per project, enabling automatic request routing to secondary queues during S3 throttling.

Description

When S3-compatible storage returns SlowDown errors (HTTP 503 rate limiting), this module provides a mechanism to temporarily flag affected projects in Redis so that their ingestion traffic can be rerouted to a secondary queue, reducing pressure on the throttled S3 endpoint.

The module exports three functions:

isS3SlowDownError: Detects whether an error object represents an S3 SlowDown error. It checks multiple error formats from the AWS SDK: name, Code, code properties, and the error message string for "SlowDown" or "reduce your request rate" patterns.

markProjectS3Slowdown: Sets a Redis key (langfuse:s3-slowdown:{projectId}) with a configurable TTL (from LANGFUSE_S3_RATE_ERROR_SLOWDOWN_TTL_SECONDS env var) to flag a project as experiencing S3 throttling. Records a metric increment for monitoring.

hasS3SlowdownFlag: Checks Redis for the existence of a project's SlowDown flag. Returns false on any error (fail-open behavior) to avoid unnecessarily redirecting traffic when Redis is unavailable.

All functions are gated by the LANGFUSE_S3_RATE_ERROR_SLOWDOWN_ENABLED environment variable and require a Redis connection to operate. When disabled or when Redis is unavailable, the functions are no-ops or return safe defaults.

Usage

Use isS3SlowDownError in S3 operation catch blocks to detect throttling. Call markProjectS3Slowdown when a SlowDown error is detected to flag the project. Use hasS3SlowdownFlag in the ingestion pipeline to decide whether to route traffic to the secondary queue.

Code Reference

Source Location

Repository: Langfuse
File: packages/shared/src/server/redis/s3SlowdownTracking.ts
Lines: 1-74

Signature

export function isS3SlowDownError(err: unknown): boolean;

export async function markProjectS3Slowdown(projectId: string): Promise<void>;

export async function hasS3SlowdownFlag(projectId: string): Promise<boolean>;

Import

import {
  isS3SlowDownError,
  markProjectS3Slowdown,
  hasS3SlowdownFlag,
} from "@langfuse/shared/src/server/redis/s3SlowdownTracking";

I/O Contract

Inputs

isS3SlowDownError

Name	Type	Required	Description
err	`unknown`	Yes	The error object to check for S3 SlowDown indicators

markProjectS3Slowdown

Name	Type	Required	Description
projectId	`string`	Yes	The project ID to flag as experiencing S3 throttling

hasS3SlowdownFlag

Name	Type	Required	Description
projectId	`string`	Yes	The project ID to check for an active SlowDown flag

Outputs

Name	Type	Description
isS3SlowDownError return	`boolean`	True if the error represents an S3 SlowDown error
markProjectS3Slowdown return	`Promise<void>`	Resolves when the flag is set (or silently fails)
hasS3SlowdownFlag return	`Promise<boolean>`	True if the project has an active SlowDown flag; false otherwise or on error

Usage Examples

import {
  isS3SlowDownError,
  markProjectS3Slowdown,
  hasS3SlowdownFlag,
} from "./s3SlowdownTracking";

// In an S3 upload catch block
try {
  await s3Client.putObject(params);
} catch (err) {
  if (isS3SlowDownError(err)) {
    await markProjectS3Slowdown(projectId);
  }
  throw err;
}

// In the ingestion routing logic
const isSlowedDown = await hasS3SlowdownFlag(projectId);
if (isSlowedDown) {
  // Route to secondary ingestion queue
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment