API Documentation

A framework for collecting and transforming SaaS logs.

grove.constants module

Constants used throughout Grove.

grove.exceptions module

Exceptions used by Grove.

exception grove.exceptions.AccessException[source]

Bases: GroveException

Indicates an issue occurred while attempting to access the requested resource.

exception grove.exceptions.ConcurrencyException[source]

Bases: GroveException

Indicates that Grove may be running in another location concurrently.

exception grove.exceptions.ConfigurationException[source]

Bases: GroveException

Indicates that a configuration related error has occurred.

exception grove.exceptions.ConnectorMissingException[source]

Bases: GroveException

Indicates that a requested connector was not found.

exception grove.exceptions.DataFormatException[source]

Bases: GroveException

Indicates an issue occurred while attempting to process data.

exception grove.exceptions.GroveException[source]

Bases: Exception

All exceptions should inherit from this to allow for hierarchical handling.

exception grove.exceptions.NotFoundException[source]

Bases: GroveException

Indicates that the requested entity was not found.

exception grove.exceptions.NotImplementedException[source]

Bases: GroveException

Indicates that the requested functionality has not been implemented.

exception grove.exceptions.ProcessorError[source]

Bases: GroveException

Indicates that an error occurred when setting up or calling a processor.

exception grove.exceptions.RateLimitException[source]

Bases: GroveException

Indicate that an upstream rate-limit was encountered.

exception grove.exceptions.RequestFailedException[source]

Bases: GroveException

Indicates that an upstream request failed for an unhandled reason.

grove.logging module

Provides a consistent logger in Grove.

class grove.logging.GroveFormatter(context: Dict[str, str], *args, **kwargs)[source]

Bases: LambdaPowertoolsFormatter

A logging formatter which emits logs in a consistent and structured way.

This formatter emits logs in JSON, with all “context” provided at creation added to each emitted message, alongside any “extra” data provided during logging calls. This formatter also adds the function name, file name, and line number of the log call to each message.

extract_keys(record: LogRecord) → Dict[str, Any][source]

Extracts and formats log records into dictionaries ready for serialisation.

This is heavily based on the code from the AWS Lambda PowerTools formatter that this formatter inherits from.

Parameters:

record – A log record to process.

Returns:

A dictionary of log data to be serialized and output.

format(record: LogRecord) → str[source]

Return the log message including any context provided by the entrypoint.

Parameters:

record – A log record to process.

Returns:

A stringified JSON document rendered from the log record.

grove.models module

Data models used throughout Grove.

class grove.models.ConnectorConfig(*, name: str, identity: str, connector: str, key: str = '', disabled: bool = False, secrets: Dict[str, str] = {}, encoding: Dict[str, str] = {}, operation: str = 'all', processors: List[ProcessorConfig] = [], outputs: Dict[str, OutputStream] = {'logs': OutputStream.raw, 'processed': OutputStream.processed}, **extra_data: Any)[source]

Bases: BaseModel

Defines the connector configuration structure.

A configuration object represents information which Grove uses to call a given connector. All connectors must have at least a name, key, identity, and connector defined.

Connector configuration objects support the addition of arbitrary fields to enable service specific authentication and configuration concerns to be defined. This is useful for services which require more than one factor for authentication, or other tuneables such as self-hosted API instance FQDN.

connector: str
disabled: bool
encoding: Dict[str, str]
identity: str
key: str
name: str
operation: str
outputs: Dict[str, OutputStream]
processors: List[ProcessorConfig]
secrets: Dict[str, str]
class grove.models.OutputStream(value)[source]

Bases: str, Enum

Defines supported output ‘streams’.

This is used to allow routing of original / raw collected data differently to post processed data.

processed = 'processed'
raw = 'raw'
class grove.models.ProcessorConfig(*, name: str, processor: str, **extra_data: Any)[source]

Bases: BaseModel

A processor configuration object.

A processor configuration object represents information used by processors to perform some set of operations on log entries. This base configuration object is bare-bones as processors may define their own required configuration fields.

name: str
processor: str
grove.models.decode(value: str, encoding: str) → str[source]

Decode a value using the specified encoding.

Parameters:

  • value – The encoded value to decode.

  • encoding – The encoding the value is encoded with.

Raises:

DataFormatException – Decoding failed due to an issue with the data, or an due to an unsupported encoding method.

Returns:

The decoded value.

grove.types module

Custom types used throughout Grove.

class grove.types.AuditLogEntries(cursor: str | None | int, entries: List[Any])[source]

Bases: NamedTuple

Provides both a pagination cursor and entries from an API response.

cursor: str | None | int

Alias for field number 0

entries: List[Any]

Alias for field number 1

class grove.types.HTTPResponse(headers: MutableMapping, body: Dict[str, Any])[source]

Bases: NamedTuple

Provides both the headers and the body of an HTTP response.

body: Dict[str, Any]

Alias for field number 1

headers: MutableMapping

Alias for field number 0

Subpackages