Shipping Service

This service is responsible for providing shipping information including pricing and tracking information, when requested from Checkout Service.

Shipping service is built primarily with Tonic, Reqwest, and OpenTelemetry Libraries/Components. Other sub-dependencies are included in Cargo.toml.

Depending on your framework and runtime, you may consider consulting Rust docs to supplement. You’ll find examples of async and sync spans in quote requests and tracking IDs respectively.

The build.rs supports development outside docker, given a Rust installation. Otherwise, consider building with docker compose to edit / assess changes as needed.

Shipping service source

Traces

Initializing Tracing

The OpenTelemetry SDK is initialized from main.

fn init_tracer() -> Result<sdktrace::Tracer, TraceError> {
    global::set_text_map_propagator(TraceContextPropagator::new());
    let os_resource = OsResourceDetector.detect(Duration::from_secs(0));
    let process_resource = ProcessResourceDetector.detect(Duration::from_secs(0));
    let sdk_resource = SdkProvidedResourceDetector.detect(Duration::from_secs(0));
    let env_resource = EnvResourceDetector::new().detect(Duration::from_secs(0));
    let telemetry_resource = TelemetryResourceDetector.detect(Duration::from_secs(0));
    opentelemetry_otlp::new_pipeline()
        .tracing()
        .with_exporter(
            opentelemetry_otlp::new_exporter()
                .tonic()
                .with_endpoint(format!(
                    "{}{}",
                    env::var("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
                        .unwrap_or_else(|_| "http://otelcol:4317".to_string()),
                    "/v1/traces"
                )), // TODO: assume this ^ is true from config when opentelemetry crate > v0.17.0
                    // https://github.com/open-telemetry/opentelemetry-rust/pull/806 includes the environment variable.
        )
        .with_trace_config(
            sdktrace::config()
                .with_resource(os_resource.merge(&process_resource).merge(&sdk_resource).merge(&env_resource).merge(&telemetry_resource)),
        )
        .install_batch(opentelemetry::runtime::Tokio)
}

Spans and other metrics are created in this example throughout tokio async runtimes found within tonic server functions. Be mindful of async runtime, context guards, and inability to move and clone spans when replicating from these samples.

Adding gRPC instrumentation

This service receives gRPC requests, which are instrumented in the middleware.

The root span is started and passed down as reference in the same thread to another closure where we call quoteservice.

    let tracer = global::tracer("shippingservice");
    let mut span = tracer.span_builder("oteldemo.ShippingService/GetQuote").with_kind(SpanKind::Server).start_with_context(&tracer, &parent_cx);
    span.set_attribute(semcov::trace::RPC_SYSTEM.string(RPC_SYSTEM_GRPC));

    span.add_event("Processing get quote request".to_string(), vec![]);

    let cx = Context::current_with_span(span);
    let q = match create_quote_from_count(itemct)
        .with_context(cx.clone())
        .await
//-> create_quote_from_count()...
    let f = match request_quote(count).await {
        Ok(float) => float,
        Err(err) => {
            let msg = format!("{}", err);
            return Err(tonic::Status::unknown(msg));
        }
    };

    Ok(get_active_span(|span| {
        let q = create_quote_from_float(f);
        span.add_event(
            "Received Quote".to_string(),
            vec![KeyValue::new("app.shipping.cost.total", format!("{}", q))],
        );
        span.set_attribute(KeyValue::new("app.shipping.items.count", count as i64));
        span.set_attribute(KeyValue::new("app.shipping.cost.total", format!("{}", q)));
        q
    }))
//<- create_quote_from_count()...
    cx.span().set_attribute(semcov::trace::RPC_GRPC_STATUS_CODE.i64(RPC_GRPC_STATUS_CODE_OK));

Note that we create a context around the root span and send a clone to the async function create_quote_from_count(). After create_quote_from_count() completes, we can add additional attributes to the root span as appropriate.

You may also notice the attributes set on the span in this example, and events propagated similarly. With any valid span pointer (attached to context) the OpenTelemetry API will work.

Adding HTTP instrumentation

A child client span is also produced for the outgoing HTTP call to quoteservice via the reqwest client. This span pairs up with the corresponding quoteservice server span. The tracing instrumentation is implemented in the client middleware making use of the available reqwest-middleware, reqwest-tracing and tracing-opentelemetry libraries:

let reqwest_client = reqwest::Client::new();
let client = ClientBuilder::new(reqwest_client)
    .with(TracingMiddleware::<SpanBackendWithUrl>::new())
    .build();

Add span attributes

Provided you are on the same thread, or in a context passed from a span-owning thread, or a ContextGuard is in scope, you can get an active span with get_active_span. You can find examples of all of these in the demo, with context available in shipping_service for sync/async runtime. You should consult quote.rs and/or the example above to see context-passed-to-async runtime.

See below for a snippet from shiporder that holds context and a span in scope. This is appropriate in our case of a sync runtime.

let parent_cx =
global::get_text_map_propagator(|prop| prop.extract(&MetadataMap(request.metadata())));
// in this case, generating a tracking ID is trivial
// we'll create a span and associated events all in this function.
let tracer = global::tracer("shippingservice");
let mut span = tracer
    .span_builder("oteldemo.ShippingService/ShipOrder").with_kind(SpanKind::Server).start_with_context(&tracer, &parent_cx);

You must add attributes to a span in context with set_attribute, followed by a KeyValue object, containing a key, and value.

let tid = create_tracking_id();
span.set_attribute(KeyValue::new("app.shipping.tracking.id", tid.clone()));
info!("Tracking ID Created: {}", tid);

Add span events

Adding span events is accomplished using add_event on the span object. Both server routes, for ShipOrderRequest (sync) and GetQuoteRequest (async), have events on spans. Attributes are not included here, but are simple to include.

Adding a span event:

let tid = create_tracking_id();
span.set_attribute(KeyValue::new("app.shipping.tracking.id", tid.clone()));
info!("Tracking ID Created: {}", tid);

Metrics

TBD

Logs

TBD


Last modified January 15, 2024: [IA] Rename /docs/instrumentation to /docs/languages, and Manual subpages to Instrumentation (#3761) (06837fe1)