Correlation System

The correlation system provides mechanisms for generating and managing correlation IDs for requests. This system enables request tracing, deduplication, and logging correlation across the service.

Correlation Providers

class CorrelationProvider

Bases: ABC

Abstract base class defining the contract for correlation ID generation.

This class serves as an interface for different strategies of generating correlation IDs. Implementations can use various methods such as hashing, UUIDs, or other approaches to generate unique identifiers.

abstractmethod get_correlation_id(input_data)

Generate a correlation ID for the given input data.

Args:

input_data: Data to use as the basis for correlation ID generation.

The type and structure of this data depends on the specific implementation.

Returns:

A string containing the generated correlation ID.

Raises:

ValueError: If the input data is not in a format supported by

the implementation.

Parameters:

input_data (bytes | str | bytearray)

Return type:

str

class HashCorrelationProvider

Bases: CorrelationProvider

Generates correlation IDs by hashing the input data.

This implementation uses SHA-256 to generate a deterministic hash of the input data’s bytes, which serves as the correlation ID.

get_correlation_id(input_data)

Generate a correlation ID by hashing the input data.

The input data is converted to bytes using the following rules: - If input is bytes, use directly - If input is str, encode as UTF-8 - Otherwise, convert to string and encode as UTF-8

Args:

input_data: Data to hash for correlation ID generation.

Returns:

A hex string of the SHA-256 hash of the input data.

Raises:

ValueError: If the input data cannot be converted to bytes.

Parameters:

input_data (bytes | str | bytearray)

Return type:

str

Usage

The correlation system is used internally by the client but can also be used directly:

options = AthenaOptions(
    correlation_provider=HashCorrelationProvider
)

async with AthenaClient(channel, options) as client:
    # The client will automatically generate correlation IDs
    results = await client.classify_images(...)

Best Practices

• Use a consistent correlation provider across related operations

• Consider data privacy when selecting correlation strategies

• Log correlation IDs for debugging and tracing

• Implement custom providers for specific needs

Custom Providers

You can implement custom correlation providers by subclassing CorrelationProvider:

class TimestampCorrelationProvider(CorrelationProvider):
    def get_correlation_id(self, input_data: bytes | str | bytearray) -> str:
        # Generate timestamp-based correlation ID
        return f"{time.time_ns()}-{hash(input_data)}"

Security Considerations

When implementing correlation systems:

• Avoid including sensitive data in correlation IDs

• Be mindful of correlation ID length and format

• Make sure each image has a unique correlation ID