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;| Module | What |
|---|---|
SkyWalkingClient | health, ping, server version, raw GraphQL, log client, tracing setup |
SkyWalkingQueryClient | services, endpoints, instances, native traces, logs, topology |
SkyWalkingTraceQueryClient | SPEC TraceQueryClient (Zipkin store for OTLP, native store for agents) |
SkyWalkingLogQueryClient | SPEC LogQueryClient (queryLogs, client-side text filter) |
init_tracing | OpenTelemetry → 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§
- blocking
blocking - 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
Loggerfacade, the query model and framework adapters. - testing
testing - 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
Attributesmap:attrs! { "user" => "ada", "n" => 3 }.
Structs§
- GraphQL
Duration - The GraphQL
Durationinput (times in the OAP timezone, formatted per step). - GraphQL
Error Info - One entry of a GraphQL
errorsarray. - GraphQL
Response - Result of a raw GraphQL call: partial
datais possible next toerrors. - Instance
Attribute - An attribute of a service instance.
- KeyValue
- A
{key, value}pair (span tags, log tags, log data). - Native
Log - A log entry as stored by OAP.
- Native
Span - A span as stored by SkyWalking (agents,
/v3/segments); identity =(segment_id, span_id). - Native
Span Log - A log entry recorded on a native span.
- Native
Span Ref - Cross-segment reference of a native span.
- Native
Trace - A native trace: every segment’s spans.
- Paging
- 1-based page selection.
- Parsed
LogQuery - Parsed form of a log search query (see
parse_log_query). - Query
Logs Options - Filter of
SkyWalkingQueryClient::query_logs. - Query
Logs Result - Result of
SkyWalkingQueryClient::query_logs. - Query
Traces Options - Filter of
SkyWalkingQueryClient::query_traces(native traces). - Query
Traces Result - Result of
SkyWalkingQueryClient::query_traces. - Resolved
Range - A window resolved to epoch milliseconds.
- SkyWalking
Capabilities - Server features probed once per client (GraphQL
hasQueryTracesV2Support,supportQueryLogsByKeywords). - SkyWalking
Client - Async client for Apache SkyWalking OAP. Cheap to clone (clones share one connection pool).
- SkyWalking
Config - Immutable client configuration; build it with
SkyWalkingConfig::builderorSkyWalkingConfig::from_env.Debugoutput redacts every credential. - SkyWalking
Config Builder - Builder for
SkyWalkingConfig. Values set here win over the environment. - SkyWalking
Endpoint - An endpoint (operation) of a service.
- SkyWalking
Instance - A service instance.
- SkyWalking
LogClient Options - Options of
SkyWalkingClient::log_client/create_log_client. - SkyWalking
LogExporter LogExporterthat 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), whateverExportOptions::gzipsays.- SkyWalking
LogQuery Client LogQueryClientfor SkyWalking (GraphQLqueryLogs). Free-text terms are filtered client side:searchreads raw pages of 1000 logs (newest first by default) and keeps the matching ones untillimitmatches ormax_scan_pagespages;next_cursor("page:offset:size") continues where it stopped. Without free text the page size islimitand nothing is filtered except the exact time window. Default window: the last hour.tailpollssearch. Obtain it fromSkyWalkingClient::logs. Cheap to clone.- SkyWalking
Query Client - The SkyWalking GraphQL query API (
POST /graphqlon port 12800). Obtain it fromSkyWalkingClient::query. Cheap to clone. - SkyWalking
Service - A service known to OAP (native agents, native logs, OTLP logs).
- SkyWalking
Trace Query Client TraceQueryClientfor SkyWalking. The backend comes fromSkyWalkingConfig::trace_backend(orwith_backend):- Sw8Context
- Decoded
sw8header (SkyWalking cross-process propagation v3). - Sw8Inject
Context Sw8Contextplus an optional correlation list, forwith_sw8_context.- Sw8Propagator
- OpenTelemetry propagator for SkyWalking headers (propagator name
sw8). - Time
Info - OAP clock and timezone (
getTimeInfo). - Time
Range - Time window of a metadata/trace/log query. Defaults:
end= now,start=end- 1 h,step=MINUTE. - Topology
getGlobalTopology/getServiceTopologyresult.- Topology
Call - An edge of the service topology.
- Topology
Node - A node of the service topology.
- Topology
Options - Options of
SkyWalkingQueryClient::topology. - Zipkin
Annotation - A Zipkin annotation (OAP encodes OTLP events as
name|attributesJSON|droppedCount). - Zipkin
Endpoint - Endpoint of a Zipkin span.
- Zipkin
Span - A span as returned by OAP’s Zipkin query API (
:9412/zipkin/api/v2).
Enums§
- LogOrder
- Order of
SkyWalkingQueryClient::query_logs. - Otlp
Protocol - OTLP protocol of the trace exporter. OAP 10.4 only serves
grpc. - Step
- Granularity of a GraphQL
Duration. - Trace
Backend - Which store the trace query client reads.
- Trace
Order - Order of
SkyWalkingQueryClient::query_traces. - Trace
State - 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.nameresource attribute. - DEFAULT_
MAX_ SCAN_ PAGES - Default number of raw pages one
searchcall may scan. - DEFAULT_
RANGE - Default query window: one hour.
- DEFAULT_
TRACE_ SEARCH_ LIMIT - Default
limitofsearch_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: whenconfig.endpointis unset, the endpoint comes fromotlp_endpoint; a protocol equal to theTracingConfigtemplate default (http/protobuf) counts as unset and becomesotlp_protocol(defaultgrpc, the only OTLP transport OAP 10.4 serves) — the same rule as TypeScript, Go and Python. Selecthttp/protobuf(an OpenTelemetry Collector in front of OAP) withSkyWalkingConfigBuilder::otlp_protocolorOTEL_EXPORTER_OTLP_PROTOCOL. Headers =otlp_headersplus theauthenticationtoken, 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
BatchingLogClientthat sends native logs toPOST /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
sw8header value;Nonewhen 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
sw8header 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
Durationfield in a timezoneoffset_minuteseast 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 throughredactand truncated to 300 characters. - graphql_
errors - Decodes the
errorsarray 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. Seeinit_tracing_with_config. - init_
tracing_ with_ config - Sets up OpenTelemetry tracing that exports to SkyWalking OAP. Endpoint, protocol, headers
and token come from
swunless theTracingConfigsets them (seeapply_skywalking_defaults). Thesw8propagator name is available (PropagatorKind::Other("sw8".into()); extract by default, seeSw8Propagator). Must be called inside a tokio runtime;CONFIGfor 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: taglevel→ severity / severity text (default INFO),span_id→span_id(16 hex), a 32-hex trace id →trace_id(native trace ids go to attributesw.trace_id), other tags → attributes (strings), service/instance → resourceservice.name/service.instance.id, endpoint → resourcesw.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’sparentSpanIdwhen ≥ 0, elserefs[0]("<parentSegmentId>-<parentSpanId>"); further refs become links.kind: Entry → server, Exit → client, Local → internal. Times ms → µs. StatuserrorwhenisError. Attributes = tags plussw.component,sw.layer,sw.peer,sw.service_instance(when set). Span logs become events (name = theeventdata value, elselog). - native_
trace_ from_ spans - Decodes a list of native spans into a
NativeTrace;Nonewhen empty. - native_
trace_ to_ trace - Converts a native trace into a SPEC
Trace(spans sorted);Nonewhen empty. - parse_
log_ query - Parses the log query syntax: space-separated
key=valueterms (service=,instance=,endpoint=,trace_id=/traceId=map to the GraphQL condition; any other key is a server tag filter and must be inSW_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).CONFIGnamingsource(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
LogRecordto nativeLogDataJSON:resource["service.name"]→service,service.instance.id→serviceInstance, body →body.text.text,severity_text→ taglevel, attributes (stringified, nested values as JSON) → tags,trace_id→traceContext.traceId(enablesrelatedTracequeries),span_id→ tagspan_id. - resolve_
range - Applies the
TimeRangedefaults;VALIDATIONwhenstartis afterend. - service_
id - SkyWalking service id of a real (normal) service:
base64(name) + ".1". - service_
id_ with - Service id:
base64(name) + ".1"whennormal,".0"for a virtual service. - skywalking_
propagators - The extra propagators this package provides (
sw8, seeSw8Propagator). - 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).nativeis 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
sw8parent (sw8.parent.*,sw8.peer). - sw8_
context - The
sw8context 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
Durationfor 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
TracingConfigforservice_namewith the SkyWalking protocol default (grpc). - with_
sw8_ context - Returns a context whose outgoing requests carry this native metadata as
sw8(andsw8-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
/zipkinpath →<address>/zipkin. - zipkin_
span_ to_ span - Converts a stored Zipkin span into the SPEC §5 model: ids lower-case (trace id padded to
32),
kindlower-case (absent →internal),service_name=localEndpoint.serviceName, status fromotel.status_code(STATUS_CODE_ERROR→ error withotel.status_description,STATUS_CODE_OK→ ok; anerrortag alone → error), attributes = tags without theotel.*,errorandw3c.tracestatebookkeeping 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);
VALIDATIONotherwise. - zipkin_
trace_ to_ trace - Converts one Zipkin trace into a SPEC
Trace;Nonewhen empty. - zipkin_
traces_ from_ body - Keeps the non-empty traces of a
[[span…]…]body.
Type Aliases§
- SkyWalking
Error - Service-prefixed alias of
Error.