Skip to main content

Crate grow_apache_skywalking

Crate grow_apache_skywalking 

Source
Expand description

§grow-apache-skywalking

Rust SDK for Apache SkyWalking by Grow Codes: the OAP GraphQL query API, OpenTelemetry tracing exported over OTLP/gRPC, native logs, sw8 propagation and the SPEC trace/log query clients.

use grow_apache_skywalking::tracing::TraceQueryClient;
use grow_apache_skywalking::{SkyWalkingClient, SkyWalkingConfig};

let client = SkyWalkingClient::new(SkyWalkingConfig::from_env()?)?;
println!("healthy: {}", client.health().await?.healthy);
println!("version: {}", client.server_version().await?);
let services = client.query().list_services(None, None).await?;
let traced = client.traces().list_services().await?;
println!("{} native services, {} traced services", services.len(), traced.len());
client.close().await;
ModuleWhat
SkyWalkingClienthealth, ping, server version, raw GraphQL, log client, tracing setup
SkyWalkingQueryClientservices, endpoints, instances, native traces, logs, topology
SkyWalkingTraceQueryClientSPEC TraceQueryClient (Zipkin store for OTLP, native store for agents)
SkyWalkingLogQueryClientSPEC LogQueryClient (queryLogs, client-side text filter)
init_tracingOpenTelemetry → OTLP/gRPC to OAP (port 11800), sw8 propagator

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

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 one-worker multi-thread tokio runtime, so background work (log batching, span export) 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).
tracing
Tracing category (SPEC §5), built on the OpenTelemetry SDK: setup, span helpers, propagation, framework adapters and the trace query model.

Macros§

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

Structs§

GraphQLDuration
The GraphQL Duration input (times in the OAP timezone, formatted per step).
GraphQLErrorInfo
One entry of a GraphQL errors array.
GraphQLResponse
Result of a raw GraphQL call: partial data is possible next to errors.
InstanceAttribute
An attribute of a service instance.
KeyValue
A {key, value} pair (span tags, log tags, log data).
NativeLog
A log entry as stored by OAP.
NativeSpan
A span as stored by SkyWalking (agents, /v3/segments); identity = (segment_id, span_id).
NativeSpanLog
A log entry recorded on a native span.
NativeSpanRef
Cross-segment reference of a native span.
NativeTrace
A native trace: every segment’s spans.
Paging
1-based page selection.
ParsedLogQuery
Parsed form of a log search query (see parse_log_query).
QueryLogsOptions
Filter of SkyWalkingQueryClient::query_logs.
QueryLogsResult
Result of SkyWalkingQueryClient::query_logs.
QueryTracesOptions
Filter of SkyWalkingQueryClient::query_traces (native traces).
QueryTracesResult
Result of SkyWalkingQueryClient::query_traces.
ResolvedRange
A window resolved to epoch milliseconds.
SkyWalkingCapabilities
Server features probed once per client (GraphQL hasQueryTracesV2Support, supportQueryLogsByKeywords).
SkyWalkingClient
Async client for Apache SkyWalking OAP. Cheap to clone (clones share one connection pool).
SkyWalkingConfig
Immutable client configuration; build it with SkyWalkingConfig::builder or SkyWalkingConfig::from_env. Debug output redacts every credential.
SkyWalkingConfigBuilder
Builder for SkyWalkingConfig. Values set here win over the environment.
SkyWalkingEndpoint
An endpoint (operation) of a service.
SkyWalkingInstance
A service instance.
SkyWalkingLogClientOptions
Options of SkyWalkingClient::log_client / create_log_client.
SkyWalkingLogExporter
LogExporter that posts batches to OAP’s native log API (POST /v3/logs, JSON array, port 12800). Native logs carry the trace context, register the service and are queryable a few seconds later. The body is sent uncompressed (gzip is not verified on OAP’s HTTP receiver), whatever ExportOptions::gzip says.
SkyWalkingLogQueryClient
LogQueryClient for SkyWalking (GraphQL queryLogs). Free-text terms are filtered client side: search reads raw pages of 1000 logs (newest first by default) and keeps the matching ones until limit matches or max_scan_pages pages; next_cursor ("page:offset:size") continues where it stopped. Without free text the page size is limit and nothing is filtered except the exact time window. Default window: the last hour. tail polls search. Obtain it from SkyWalkingClient::logs. Cheap to clone.
SkyWalkingQueryClient
The SkyWalking GraphQL query API (POST /graphql on port 12800). Obtain it from SkyWalkingClient::query. Cheap to clone.
SkyWalkingService
A service known to OAP (native agents, native logs, OTLP logs).
SkyWalkingTraceQueryClient
TraceQueryClient for SkyWalking. The backend comes from SkyWalkingConfig::trace_backend (or with_backend):
Sw8Context
Decoded sw8 header (SkyWalking cross-process propagation v3).
Sw8InjectContext
Sw8Context plus an optional correlation list, for with_sw8_context.
Sw8Propagator
OpenTelemetry propagator for SkyWalking headers (propagator name sw8).
TimeInfo
OAP clock and timezone (getTimeInfo).
TimeRange
Time window of a metadata/trace/log query. Defaults: end = now, start = end - 1 h, step = MINUTE.
Topology
getGlobalTopology / getServiceTopology result.
TopologyCall
An edge of the service topology.
TopologyNode
A node of the service topology.
TopologyOptions
Options of SkyWalkingQueryClient::topology.
ZipkinAnnotation
A Zipkin annotation (OAP encodes OTLP events as name|attributesJSON|droppedCount).
ZipkinEndpoint
Endpoint of a Zipkin span.
ZipkinSpan
A span as returned by OAP’s Zipkin query API (:9412/zipkin/api/v2).

Enums§

LogOrder
Order of SkyWalkingQueryClient::query_logs.
OtlpProtocol
OTLP protocol of the trace exporter. OAP 10.4 only serves grpc.
Step
Granularity of a GraphQL Duration.
TraceBackend
Which store the trace query client reads.
TraceOrder
Order of SkyWalkingQueryClient::query_traces.
TraceState
Trace state filter of SkyWalkingQueryClient::query_traces.

Constants§

AUTHENTICATION_HEADER
gRPC metadata key OAP reads the token from (SW_AUTHENTICATION).
DEFAULT_GRAPHQL_PATH
Default GraphQL path below the URL.
DEFAULT_LOG_SERVICE_NAME
Service name used when a record has no service.name resource attribute.
DEFAULT_MAX_SCAN_PAGES
Default number of raw pages one search call may scan.
DEFAULT_RANGE
Default query window: one hour.
DEFAULT_TRACE_SEARCH_LIMIT
Default limit of search_traces (SPEC §5).
DEFAULT_URL
REST/GraphQL endpoint used when neither the builder nor the environment sets one.
LOG_SCAN_PAGE_SIZE
Raw page size used while filtering free text client side.
NATIVE_SPAN_FIELDS
GraphQL selection used for native spans.
OTLP_GRPC_PORT
OAP gRPC port (OTLP receiver).
SW8_CORRELATION_HEADER
Header name of the SkyWalking correlation context.
SW8_HEADER
Header name of the SkyWalking v3 trace context.
SW8_PROPAGATOR
Name of the propagator in TracingConfig::propagators (PropagatorKind::Other("sw8")).
VENDOR_AUTHENTICATION_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_AUTHENTICATION.
VENDOR_OTLP_ENDPOINT_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_OTLP_ENDPOINT.
VENDOR_OTLP_HEADERS_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_OTLP_HEADERS.
VENDOR_OTLP_PROTOCOL_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_OTLP_PROTOCOL.
VENDOR_TRACE_BACKEND_VARS
Vendor variables checked after GROW_APACHE_SKYWALKING_TRACE_BACKEND.
VENDOR_URL_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_URL.
VENDOR_ZIPKIN_URL_VARS
Vendor variables checked (in order) after GROW_APACHE_SKYWALKING_ZIPKIN_URL.
ZIPKIN_QUERY_PORT
OAP Zipkin query port (SW_QUERY_ZIPKIN).

Functions§

annotation_to_event
Decodes an OAP annotation into an event: name|{"k":"v"}|0 (split on the first and last |) → name + attributes; any other value is the event name without attributes.
apply_skywalking_defaults
Merges the SkyWalking defaults under config: when config.endpoint is unset, the endpoint comes from otlp_endpoint; a protocol equal to the TracingConfig template default (http/protobuf) counts as unset and becomes otlp_protocol (default grpc, the only OTLP transport OAP 10.4 serves) — the same rule as TypeScript, Go and Python. Select http/protobuf (an OpenTelemetry Collector in front of OAP) with SkyWalkingConfigBuilder::otlp_protocol or OTEL_EXPORTER_OTLP_PROTOCOL. Headers = otlp_headers plus the authentication token, overridden by the config’s own headers; TLS from the SkyWalking config when the config has none.
base_from_graphql_url
Strips a trailing /graphql (with or without slash, any case) from a GraphQL URL.
collector_to_url
host:port[,host:port] (SkyWalking agent collector address) → http://host:port; values that already carry a scheme are returned as is.
create_log_client
Standalone BatchingLogClient that sends native logs to POST /v3/logs (owns its connections; close() flushes and releases them). Must be called inside a tokio runtime.
decode_native_log
Decodes one native log.
decode_native_span
Decodes one native span from a GraphQL response (missing fields get neutral defaults).
decode_sw8
Decodes an sw8 header value; None when it is malformed (wrong field count, bad Base64, non-numeric span id, empty trace or segment id).
decode_sw8_correlation
Decodes sw8-correlation; malformed entries are skipped.
decode_topology
Decodes a topology result.
encode_sw8
Encodes an sw8 header value: sample-b64(traceId)-b64(segment)-spanId-b64(service)-b64(instance)-b64(endpoint)-b64(peer).
encode_sw8_correlation
Encodes sw8-correlation: b64(key):b64(value),… in order.
endpoint_id
Endpoint id: serviceId + "_" + base64(endpointName).
epoch_ms
Epoch milliseconds of a time (negative before 1970).
format_duration_time
Formats an epoch-ms time for a Duration field in a timezone offset_minutes east of UTC: DAY yyyy-MM-dd, HOUR yyyy-MM-dd HH, MINUTE yyyy-MM-dd HHmm, SECOND yyyy-MM-dd HHmmss.
from_epoch_ms
The time at an epoch millisecond (clamped at 1970).
graphql_error
Maps GraphQL errors to an SDK error: UnsupportedOperationException → UNSUPPORTED, everything else → VALIDATION (bad input caught by the resolver). The message is passed through redact and truncated to 300 characters.
graphql_errors
Decodes the errors array of a GraphQL response body.
init_tracing
Sets up OpenTelemetry tracing that exports OTLP/gRPC to SkyWalking OAP (SPEC §5), with the connection settings from SkyWalkingConfig::from_env. See init_tracing_with_config.
init_tracing_with_config
Sets up OpenTelemetry tracing that exports to SkyWalking OAP. Endpoint, protocol, headers and token come from sw unless the TracingConfig sets them (see apply_skywalking_defaults). The sw8 propagator name is available (PropagatorKind::Other("sw8".into()); extract by default, see Sw8Propagator). Must be called inside a tokio runtime; CONFIG for invalid settings.
instance_id
Service instance id: serviceId + "_" + base64(instanceName).
is_bookkeeping_tag
Tags OAP adds as bookkeeping; they are mapped to status/kind and dropped from attributes.
is_hex_trace_id
True for a 16- or 32-character hex id (OTLP/Zipkin), false for native SkyWalking ids.
key_values
Decodes a [{key, value}] list (non-string values are stringified, null → "").
log_to_record
Maps a stored log back to a SPEC LogRecord: tag level → severity / severity text (default INFO), span_id → span_id (16 hex), a 32-hex trace id → trace_id (native trace ids go to attribute sw.trace_id), other tags → attributes (strings), service/instance → resource service.name / service.instance.id, endpoint → resource sw.endpoint.
matches_text
True when every term occurs (case-insensitive) in the log content or one of its tag values.
native_span_key
Composite SPEC span id of a native span: <segmentId>-<spanId>.
native_span_to_span
Converts a native span into the SPEC §5 model. Ids are kept verbatim: span_id = "<segmentId>-<spanId>"; the parent is the same segment’s parentSpanId when ≥ 0, else refs[0] ("<parentSegmentId>-<parentSpanId>"); further refs become links. kind: Entry → server, Exit → client, Local → internal. Times ms → µs. Status error when isError. Attributes = tags plus sw.component, sw.layer, sw.peer, sw.service_instance (when set). Span logs become events (name = the event data value, else log).
native_trace_from_spans
Decodes a list of native spans into a NativeTrace; None when empty.
native_trace_to_trace
Converts a native trace into a SPEC Trace (spans sorted); None when empty.
parse_log_query
Parses the log query syntax: space-separated key=value terms (service=, instance=, endpoint=, trace_id=/traceId= map to the GraphQL condition; any other key is a server tag filter and must be in SW_SEARCHABLE_LOGS_TAG_KEYS) plus free-text terms ("quoted phrases" allowed). Every free-text term must occur (case-insensitive) in the content or in a tag value.
parse_otlp_headers
Parses OTEL-style headers k1=v1,k2=v2 (values percent-decoded, keys lower-cased). CONFIG naming source (never the value) when an entry is malformed.
parse_timezone
Parses an OAP timezone (getTimeInfo.timezone, e.g. +0000, -0530, +08:00) into minutes east of UTC. Unknown text → 0.
record_to_log_data
Maps a SPEC LogRecord to native LogData JSON: resource["service.name"] → service, service.instance.id → serviceInstance, body → body.text.text, severity_text → tag level, attributes (stringified, nested values as JSON) → tags, trace_id → traceContext.traceId (enables relatedTrace queries), span_id → tag span_id.
resolve_range
Applies the TimeRange defaults; VALIDATION when start is after end.
service_id
SkyWalking service id of a real (normal) service: base64(name) + ".1".
service_id_with
Service id: base64(name) + ".1" when normal, ".0" for a virtual service.
skywalking_propagators
The extra propagators this package provides (sw8, see Sw8Propagator).
skywalking_span_exporter
Builds the span exporter: grpc → OTLP/gRPC to the OAP receiver (headers become gRPC metadata); http/protobuf → OTLP/HTTP protobuf to <endpoint>/v1/traces (only for an OpenTelemetry Collector in front of OAP — OAP 10.4 serves no OTLP/HTTP). native is not supported (CONFIG): use the official SkyWalking agents.
strings_from_body
Decodes a string[] body.
summarize
Summarises a SPEC trace; the root falls back to the earliest span.
sw8_attributes
Span attributes describing an extracted sw8 parent (sw8.parent.*, sw8.peer).
sw8_context
The sw8 context extracted from an incoming request, if any.
tag_text
Converts an attribute value to SkyWalking’s string tag form (JSON for arrays/objects).
to_graphql_duration
Builds the GraphQL Duration for a resolved window.
topology_to_dependencies
Topology → dependency links (parent = source node name, child = target node name, call_count = 0 because the topology carries no call counts). Sorted by parent, child.
tracing_config
A TracingConfig for service_name with the SkyWalking protocol default (grpc).
with_sw8_context
Returns a context whose outgoing requests carry this native metadata as sw8 (and sw8-correlation). The SDK cannot derive native metadata from an OpenTelemetry span; supply it only when you bridge to SkyWalking agents.
zipkin_query_url
A Zipkin address with or without the /zipkin path → <address>/zipkin.
zipkin_span_to_span
Converts a stored Zipkin span into the SPEC §5 model: ids lower-case (trace id padded to 32), kind lower-case (absent → internal), service_name = localEndpoint.serviceName, status from otel.status_code (STATUS_CODE_ERROR → error with otel.status_description, STATUS_CODE_OK → ok; an error tag alone → error), attributes = tags without the otel.*, error and w3c.tracestate bookkeeping keys (values are strings: OAP stores tags as text), annotations → events. Span names are lower-cased by OAP on ingest.
zipkin_spans_from_body
Keeps the well-formed spans of a response body.
zipkin_trace_id
Lower-cases and validates a Zipkin trace id (16 or 32 hex, not all zeros); VALIDATION otherwise.
zipkin_trace_to_trace
Converts one Zipkin trace into a SPEC Trace; None when empty.
zipkin_traces_from_body
Keeps the non-empty traces of a [[span…]…] body.

Type Aliases§

SkyWalkingError
Service-prefixed alias of Error.