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§
- blocking
blocking - 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
Loggerfacade, the query model and framework adapters. - testing
testing - Test support (feature
testing): in-memory fakes and the conformance runner (SPEC §6).
Macros§
- attrs
- Builds an
Attributesmap:attrs! { "user" => "ada", "n" => 3 }.
Structs§
- Create
Input Options - Options of
GraylogClient::create_input. - Create
Stream Options - Description of a new stream (
GraylogClient::create_stream).titleis required. - Ensure
Gelf Input Options - Options of
GraylogClient::ensure_gelf_input. The default is valid. - Ensured
Input - Result of
GraylogClient::ensure_gelf_input. - From
LogRecord Options - Options of
GelfMessage::from_log_record. - Gelf
Http Options - Options of
GelfHttpTransport::new. - Gelf
Http Transport - Posts GELF messages to a GELF HTTP input (202 Accepted). Graylog answers 202 even for
invalid JSON or a missing
short_messageand drops the message, so messages are validated when they are built. - Gelf
LogExporter - The
LogExporterof the logging category: converts records withGelfMessage::from_log_recordand sends them through aGelfTransport. - Gelf
Message - One GELF 1.1 message. Build it with
GelfMessage::newandset_field, or from aLogRecordwithGelfMessage::from_log_record.Displayrenders the compact JSON text. - Gelf
Message Options - Description of a
GelfMessage;hostandshort_messageare required. - Gelf
Send Options - Per-call options of
GelfTransport::send. - Gelf
Send Result - Outcome of
GelfTransport::send. - Gelf
TcpOptions - Options of
GelfTcpTransport::new. - Gelf
TcpTransport - 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). - Gelf
Transport Options - Options of
GraylogClient::gelf_transport. - Gelf
UdpOptions - Options of
GelfUdpTransport::new. - Gelf
UdpTransport - Fire-and-forget datagrams: compressed, chunked up to 128 chunks. Delivery is best-effort (UDP has no acknowledgement).
- Graylog
Client - Async client for Graylog Open. Cheap to clone (clones share one connection pool).
- Graylog
Config - Immutable client configuration; build it with
GraylogConfig::builderorGraylogConfig::from_env.Debugoutput redacts every credential. - Graylog
Config Builder - Builder for
GraylogConfig. Values set here win over the environment. - Index
Set - An index set.
- Input
- A message input (
GET /api/system/inputs). - Input
State - Runtime state of an input (
GET /api/system/inputstates/{id}). - List
Streams Options - 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
LogQueryClientof this SDK. Queries use Graylog’s Lucene syntax (marker:abc,"exact phrase",level:<=3,trace_id:4bf9…). - LogQuery
Options - Options of
GraylogClient::log_query. The default is valid. - Message
- One search hit or stored message.
- Message
Search Options - Options of
GraylogClient::search. Give at most one ofrange,start/endandkeyword; the default searches the last 5 minutes of every readable stream, newest first, 100 per page. - Message
Search Result - One page of
GraylogClient::search. - Otlp
Grpc LogExporter - The
LogExporterfor the Graylog OpenTelemetry (gRPC) input (org.graylog.inputs.otel.OTelGrpcInput): OTLPLogsService/Exportover gRPC, gzip when the batch asks for it. Graylog storesotel_*fields;log_record_from_messagereads them back. - Otlp
Grpc LogExporter Options - Options of
OtlpGrpcLogExporter::new. - Otlp
Partial Success partial_successof anExportLogsServiceResponse.- Search
Sort - One sort key of
GraylogClient::search. - Stream
- A stream.
- Stream
Page - One page of streams.
- Stream
Rule - One rule of a stream.
- System
Info - Node information (
GET /api/system).
Enums§
- Gelf
Compression - Payload compression of the UDP transport.
- Gelf
Level - The GELF
levelfield: a syslog severity 0–7. - Gelf
Protocol - 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’ssearchwhen no start is given (1 h). - DEFAULT_
MESSAGE_ SORT_ FIELD - Sort field of
GraylogClient::searchwhen none is given. - DEFAULT_
OTLP_ GRPC_ PORT - Default port of the OpenTelemetry (gRPC) input.
- DEFAULT_
REQUESTED_ BY - Default
X-Requested-Byvalue (Graylog requires the header on every non-GET request). - DEFAULT_
SEARCH_ LIMIT - Page size of
GraylogClient::searchwhen none is given. - DEFAULT_
SEARCH_ RANGE - Relative range of
GraylogClient::searchwhen no range is given (300 s). - DEFAULT_
TAIL_ INTERVAL - Poll interval of
LogQuery’stailwhen 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
searchrequests (OpenSearch’s defaultmax_result_windowfor 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 asotel_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§
- Gelf
Transport - Sends GELF messages to a Graylog input. Implementations are safe for concurrent use.
Functions§
- decode_
export_ logs_ response - Decodes an
ExportLogsServiceResponse(VALIDATIONfor malformed bytes). - encode_
export_ logs_ request - Encodes records as one protobuf
ExportLogsServiceRequest: oneResourceLogsper distinct resource (first-seen order) with oneScopeLogseach (scopeOTLP_SCOPE_NAME). - encode_
gelf_ udp - Compresses
payloadand splits it into datagrams: one datagram when it fitschunk_size, else chunks0x1e 0x0f | id(8) | seq | count | data. More than 128 chunks is aVALIDATIONerror.message_id = Noneuses 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_, andid(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.nullreturnsNone(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 aLogRecord. 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 (
nameor_name) and returns the_namewire key. Keys outside[A-Za-z0-9_.-], empty keys and the reservedidareVALIDATIONerrors.
Type Aliases§
- Graylog
Error - Service-prefixed alias of
Error.