Skip to main content

Crate grow_graylog

Crate grow_graylog 

Source
Expand description

§grow-graylog

Rust SDK for Graylog Open by Grow Codes.

use grow_graylog::logging::{attrs, LogClient, LogQueryClient, WaitOptions};
use grow_graylog::{GraylogClient, GraylogConfig, LogOptions, LogQueryOptions};

let client = GraylogClient::new(GraylogConfig::from_env()?)?;
let health = client.health().await?;
println!("healthy: {}", health.healthy);

// GELF over the configured protocol (TCP by default), batched.
let logs = client.new_log_client(LogOptions::default().resource_attribute("service.name", "checkout"))?;
logs.logger(Some("http"), attrs! {}).info("order placed", attrs! { "order_id" => "o-1" });
logs.flush(None).await?;

// Read it back through the Views search API.
let record = client
    .log_query(LogQueryOptions::default())
    .wait_for_log("order_id:o-1", WaitOptions::default())
    .await?;
println!("{}", record.body);
client.close().await;

Modules: GELF messages and transports (GelfMessage, GelfUdpTransport, GelfTcpTransport, GelfHttpTransport), the optional OTLP/gRPC exporter (OtlpGrpcLogExporter), search (GraylogClient::search, GraylogClient::search_relative, GraylogClient::get_message), admin (inputs, streams, index sets, GraylogClient::system_info) and the logging category (GraylogClient::new_log_client, GraylogClient::log_query).

Features: blocking (a blocking client), testing (in-memory fakes and the conformance runner), tracing-layer and log-bridge (logging adapters, on by default).

Graylog is a trademark of Graylog, Inc. This project is not affiliated with or endorsed by Graylog, Inc.

Re-exports§

pub use crate::core::Error;
pub use crate::core::ErrorCode;
pub use crate::core::HealthStatus;
pub use crate::core::Result;
pub use crate::core::RetryPolicy;
pub use crate::core::Secret;

Modules§

blockingblocking
Blocking wrapper (feature blocking). Each client owns a small tokio runtime with one worker thread, so background work (tails, batching log clients) keeps running between calls.
core
Shared core: errors, configuration, secrets in config, redaction, retries and transport.
logging
Logging category (SPEC §4): records, batching, redaction, the Logger facade, the query model and framework adapters.
testingtesting
Test support (feature testing): in-memory fakes and the conformance runner (SPEC §6).

Macros§

attrs
Builds an Attributes map: attrs! { "user" => "ada", "n" => 3 }.

Structs§

CreateInputOptions
Options of GraylogClient::create_input.
CreateStreamOptions
Description of a new stream (GraylogClient::create_stream). title is required.
EnsureGelfInputOptions
Options of GraylogClient::ensure_gelf_input. The default is valid.
EnsuredInput
Result of GraylogClient::ensure_gelf_input.
FromLogRecordOptions
Options of GelfMessage::from_log_record.
GelfHttpOptions
Options of GelfHttpTransport::new.
GelfHttpTransport
Posts GELF messages to a GELF HTTP input (202 Accepted). Graylog answers 202 even for invalid JSON or a missing short_message and drops the message, so messages are validated when they are built.
GelfLogExporter
The LogExporter of the logging category: converts records with GelfMessage::from_log_record and sends them through a GelfTransport.
GelfMessage
One GELF 1.1 message. Build it with GelfMessage::new and set_field, or from a LogRecord with GelfMessage::from_log_record. Display renders the compact JSON text.
GelfMessageOptions
Description of a GelfMessage; host and short_message are required.
GelfSendOptions
Per-call options of GelfTransport::send.
GelfSendResult
Outcome of GelfTransport::send.
GelfTcpOptions
Options of GelfTcpTransport::new.
GelfTcpTransport
NUL-terminated JSON frames over one long-lived connection (input option use_null_delimiter). Batches never interleave. A connection closed by the server is detected before each batch and re-opened; a failed batch is re-sent on a new connection (at-least-once).
GelfTransportOptions
Options of GraylogClient::gelf_transport.
GelfUdpOptions
Options of GelfUdpTransport::new.
GelfUdpTransport
Fire-and-forget datagrams: compressed, chunked up to 128 chunks. Delivery is best-effort (UDP has no acknowledgement).
GraylogClient
Async client for Graylog Open. Cheap to clone (clones share one connection pool).
GraylogConfig
Immutable client configuration; build it with GraylogConfig::builder or GraylogConfig::from_env. Debug output redacts every credential.
GraylogConfigBuilder
Builder for GraylogConfig. Values set here win over the environment.
IndexSet
An index set.
Input
A message input (GET /api/system/inputs).
InputState
Runtime state of an input (GET /api/system/inputstates/{id}).
ListStreamsOptions
Options of GraylogClient::list_streams. The default is page 1, 50 per page, sorted by title ascending.
LogOptions
Options of GraylogClient::new_log_client: the batching options plus the transport choice.
LogQuery
The LogQueryClient of this SDK. Queries use Graylog’s Lucene syntax (marker:abc, "exact phrase", level:<=3, trace_id:4bf9…).
LogQueryOptions
Options of GraylogClient::log_query. The default is valid.
Message
One search hit or stored message.
MessageSearchOptions
Options of GraylogClient::search. Give at most one of range, start/end and keyword; the default searches the last 5 minutes of every readable stream, newest first, 100 per page.
MessageSearchResult
One page of GraylogClient::search.
OtlpGrpcLogExporter
The LogExporter for the Graylog OpenTelemetry (gRPC) input (org.graylog.inputs.otel.OTelGrpcInput): OTLP LogsService/Export over gRPC, gzip when the batch asks for it. Graylog stores otel_* fields; log_record_from_message reads them back.
OtlpGrpcLogExporterOptions
Options of OtlpGrpcLogExporter::new.
OtlpPartialSuccess
partial_success of an ExportLogsServiceResponse.
SearchSort
One sort key of GraylogClient::search.
Stream
A stream.
StreamPage
One page of streams.
StreamRule
One rule of a stream.
SystemInfo
Node information (GET /api/system).

Enums§

GelfCompression
Payload compression of the UDP transport.
GelfLevel
The GELF level field: a syslog severity 0–7.
GelfProtocol
Log transport: the three GELF transports plus OTLP/gRPC.

Constants§

DEFAULT_GELF_HTTP_PORT
Default GELF HTTP port (Graylog has no fixed one; 12202 is the common choice).
DEFAULT_GELF_PORT
Default GELF UDP and TCP port.
DEFAULT_LOG_QUERY_WINDOW
Search window of LogQuery’s search when no start is given (1 h).
DEFAULT_MESSAGE_SORT_FIELD
Sort field of GraylogClient::search when none is given.
DEFAULT_OTLP_GRPC_PORT
Default port of the OpenTelemetry (gRPC) input.
DEFAULT_REQUESTED_BY
Default X-Requested-By value (Graylog requires the header on every non-GET request).
DEFAULT_SEARCH_LIMIT
Page size of GraylogClient::search when none is given.
DEFAULT_SEARCH_RANGE
Relative range of GraylogClient::search when no range is given (300 s).
DEFAULT_TAIL_INTERVAL
Poll interval of LogQuery’s tail when the options keep the template default (2 s).
DEFAULT_UDP_CHUNK_SIZE
Default datagram size including the chunk header (fits a 1500-byte Ethernet MTU).
DEFAULT_URL
Endpoint used when neither the builder nor the environment sets one.
GELF_CHUNK_HEADER_SIZE
Chunk header: magic (2), message id (8), sequence number (1), sequence count (1).
GELF_CHUNK_MAGIC
Chunk magic bytes 0x1e 0x0f.
GELF_MAX_CHUNKS
GELF limit of chunks per message.
GELF_VERSION
GELF specification version written into every message.
HEADER_NODE_ID
Response header that names the Graylog node.
HEADER_REQUESTED_BY
Graylog’s CSRF guard header; required on every non-GET request (HTTP 400 without it). The client always sends it.
INPUT_STATE_FAILED
Input state of an input that could not start (for example a busy port).
INPUT_STATE_RUNNING
Input state of a started input.
INPUT_TYPE_GELF_HTTP
GELF HTTP input class.
INPUT_TYPE_GELF_TCP
GELF TCP input class.
INPUT_TYPE_GELF_UDP
GELF UDP input class.
INPUT_TYPE_OTEL_GRPC
OpenTelemetry (gRPC) input class.
MAX_SEARCH_LIMIT
Largest page search requests (OpenSearch’s default max_result_window for offset + limit).
OTLP_LOGS_EXPORT_PATH
gRPC method path of the OTLP logs service.
OTLP_SCOPE_NAME
Instrumentation scope written into every OTLP export.
RESOURCE_FIELDS
Stored field names mapped back to OpenTelemetry resource keys (Graylog replaces . with _; OTLP resource attributes arrive as otel_resource_attributes_<name>).
STREAM_RULE_ALWAYS_MATCH
Stream rule type: always match.
STREAM_RULE_CONTAINS
Stream rule type: contains.
STREAM_RULE_EXACT
Stream rule type: exact match.
STREAM_RULE_GREATER
Stream rule type: greater than.
STREAM_RULE_MATCH_INPUT
Stream rule type: match input.
STREAM_RULE_PRESENCE
Stream rule type: field presence.
STREAM_RULE_REGEX
Stream rule type: regular expression.
STREAM_RULE_SMALLER
Stream rule type: smaller than.

Traits§

GelfTransport
Sends GELF messages to a Graylog input. Implementations are safe for concurrent use.

Functions§

decode_export_logs_response
Decodes an ExportLogsServiceResponse (VALIDATION for malformed bytes).
encode_export_logs_request
Encodes records as one protobuf ExportLogsServiceRequest: one ResourceLogs per distinct resource (first-seen order) with one ScopeLogs each (scope OTLP_SCOPE_NAME).
encode_gelf_udp
Compresses payload and splits it into datagrams: one datagram when it fits chunk_size, else chunks 0x1e 0x0f | id(8) | seq | count | data. More than 128 chunks is a VALIDATION error. message_id = None uses a random id.
error_for_grpc_status
Maps a gRPC status code to the SDK error: CANCELLED, INVALID_ARGUMENT/FAILED_PRECONDITION → VALIDATION, DEADLINE_EXCEEDED → TIMEOUT, NOT_FOUND, ALREADY_EXISTS → CONFLICT, PERMISSION_DENIED, RESOURCE_EXHAUSTED → RATE_LIMITED, UNIMPLEMENTED → UNSUPPORTED, UNAUTHENTICATED → AUTHENTICATION; ABORTED, OUT_OF_RANGE, UNAVAILABLE and DATA_LOSS → retryable UNAVAILABLE; anything else → non-retryable UNAVAILABLE.
flatten_attributes
Flattens nested maps into dotted keys; arrays and scalars are leaves.
frame_gelf_tcp
Encodes messages as NUL-terminated JSON frames.
gelf_field_key
Maps an attribute name to its GELF additional field key (the rule shared by all five languages): a _ prefix, every character outside [A-Za-z0-9_.-] replaced by _, and id (reserved by GELF) → _attr_id.
gelf_field_value
Maps an attribute value to its GELF form: strings and numbers unchanged, booleans → "true"/"false" (Graylog drops JSON booleans), arrays and maps → compact JSON strings. null returns None (the field is omitted).
gelf_level_to_severity
Maps a syslog level to a severity: 0–2 → FATAL, 3 → ERROR, 4 → WARN, 5–6 → INFO, 7 → DEBUG (below 0 → FATAL, above 7 → DEBUG).
gelf_timestamp
Renders a time as Unix seconds with millisecond precision (a JSON number such as 1795000000.123).
log_record_from_message
Normalizes stored Graylog message fields (a search hit or GraylogClient::get_message) into a LogRecord. OTLP fields (otel_*) win over GELF fields:
severity_to_gelf_level
Maps a severity to a syslog level: TRACE/DEBUG → 7, INFO → 6, WARN → 4, ERROR → 3, FATAL → 2.
validate_gelf_field_key
Validates an explicit additional field key (name or _name) and returns the _name wire key. Keys outside [A-Za-z0-9_.-], empty keys and the reserved id are VALIDATION errors.

Type Aliases§

GraylogError
Service-prefixed alias of Error.