Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(whatsmeow): trace connects, IQs and messages without leaking JIDs (#8724)

Wolf Mermelsteine1eb8e2e6f04
diff --git a/Cargo.lock b/Cargo.lock
index 0bac64528d..ba54af354b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -21751,6 +21751,7 @@ dependencies = [
"tokio-tungstenite 0.28.0",
"tokio-util",
"tracing",
+ "tracing-subscriber",
"uuid",
"whatsmeow_proto",
"workspace-hack",
diff --git a/crates/whatsmeow/AGENTS.md b/crates/whatsmeow/AGENTS.md
index 6f84fb66df..ed1e2460b3 100644
--- a/crates/whatsmeow/AGENTS.md
+++ b/crates/whatsmeow/AGENTS.md
@@ -138,6 +138,36 @@ WASA/bot parts of `msgsecret.go`, reporting tokens, `armadillomessage.go`, `push
- Log opaque values only (tags, IDs, counts); unlike Go, never log node XML,
JIDs or phone numbers.
+## Telemetry (a Macro addition)
+
+whatsmeow has no tracing spans; the spans here are Macro's, added around the
+ported logic without changing it. Helpers live in `src/telemetry.rs`; its test
+captures spans from a client on the fake server.
+
+- Spans nest under the caller: `Client::connect` stores the current span
+ (`connection_parent`), the connection's loops, reconnects and history sync
+ run under it, and `Client::spawn` keeps the spawning span
+ (`in_current_span`).
+- `whatsmeow.connect` (`reason`: `initial`, `restart_515`, `network_drop`,
+ `forced_reset`, `keepalive_timeout`, `connect_failed`; `attempt`) with
+ children `.dial`, `.handshake`, `.login` (ends at `success`/`failure`, or
+ after the post-login prekey and passive requests). Disconnects that don't
+ reconnect log `disconnect_reason` (`conflict_replaced`, `logged_out`).
+- `whatsmeow.iq` per info query: `xmlns`, `iq_type`, `kind` (first child
+ tag), `outcome` (`ok`, `error` + `error_code`, `timeout`, `disconnected`).
+ Not `err`: an IQ error's message can hold the raw response node.
+- Receive: `whatsmeow.receive_message` counts `decrypted`, flags
+ `decrypt_failed`/`retry_receipt`, records `ack_ms`; each `<enc>` gets a
+ DEBUG `whatsmeow.decrypt` span (`enc_type`, `outcome`).
+- Send (`devices` fan-out, encrypt and `wait_ack` phases), media
+ (`whatsmeow.media.encrypt`, `.upload_http`, `.fetch` with `size`,
+ `retries`, `hash_check`), app state (`patches`, `events`),
+ `whatsmeow.history_sync.process`, `whatsmeow.prekeys.upload`,
+ `whatsmeow.retry_receipt.send`.
+- Failed spans set `otel.status_code = "ERROR"` (declare it `Empty`). Fields
+ are kinds, counts, outcomes and random message ids; never JIDs, phone
+ numbers, content or keys.
+
## Signal protocol boundary
Every Signal call goes through the traits in `src/signal.rs`:
diff --git a/crates/whatsmeow/Cargo.toml b/crates/whatsmeow/Cargo.toml
index 5eb68e8f4f..940d35f7cc 100644
--- a/crates/whatsmeow/Cargo.toml
+++ b/crates/whatsmeow/Cargo.toml
@@ -49,3 +49,4 @@ testing = []
axum = { workspace = true }
tempfile = { workspace = true }
tokio = { workspace = true, features = ["io-util", "macros", "net", "rt", "test-util"] }
+tracing-subscriber = { workspace = true }
diff --git a/crates/whatsmeow/src/appstate/client.rs b/crates/whatsmeow/src/appstate/client.rs
index 8ac3949e82..668b5535c6 100644
--- a/crates/whatsmeow/src/appstate/client.rs
+++ b/crates/whatsmeow/src/appstate/client.rs
@@ -106,7 +106,7 @@ impl Client {
#[tracing::instrument(
name = "whatsmeow.app_state.fetch",
skip_all,
- fields(name = %name, full_sync, only_if_not_synced),
+ fields(name = %name, full_sync, only_if_not_synced, patches, events),
err
)]
async fn fetch_app_state_events(
@@ -143,6 +143,7 @@ impl Client {
let mut want_snapshot = full_sync;
let mut events = Vec::new();
let emit = !full_sync || self.config.emit_app_state_events_on_full_sync;
+ let mut patch_count = 0_usize;
while has_more {
let patches = match self
.fetch_app_state_patches(name, state.version, want_snapshot)
@@ -173,6 +174,9 @@ impl Client {
}
want_snapshot = false;
has_more = patches.has_more_patches;
+ // Macro addition: how much the sync applied.
+ patch_count += patches.patches.len();
+ tracing::Span::current().record("patches", patch_count);
state = self
.apply_app_state_patches(
name,
@@ -193,6 +197,7 @@ impl Client {
} else {
tracing::debug!(name = %name, from = version, to = state.version, "synced app state");
}
+ tracing::Span::current().record("events", events.len());
Ok(events)
}
diff --git a/crates/whatsmeow/src/client.rs b/crates/whatsmeow/src/client.rs
index 2f0fbb562a..b306aa3991 100644
--- a/crates/whatsmeow/src/client.rs
+++ b/crates/whatsmeow/src/client.rs
@@ -44,6 +44,7 @@ use crate::pair_code::PairClientType;
use crate::signal::{CurveSignatures, SignalProtocol};
use crate::socket::{FrameEvent, FrameSocket, NoiseEvent, NoiseSocket, SocketError, URL};
use crate::store::{Device, StoreError};
+use crate::telemetry::ConnectReason;
use crate::types::events::{Disconnected, Event};
use crate::types::{AddressingMode, DEFAULT_USER_SERVER, HIDDEN_USER_SERVER, Jid};
use crate::util::keys::new_key_pair;
@@ -376,6 +377,14 @@ pub struct Client {
/// Cancelled when the client is dropped or shut down (Go's
/// `BackgroundEventCtx`).
pub(crate) background: CancellationToken,
+
+ /// Macro addition: the span that was current when [`Client::connect`]
+ /// was called. Connection spans, reconnects and received nodes nest
+ /// under it.
+ pub(crate) connection_parent: Mutex<tracing::Span>,
+ /// Macro addition: the `whatsmeow.connect.login` span between the
+ /// handshake and the server's `success` or `failure`.
+ pub(crate) pending_login: Mutex<Option<tracing::Span>>,
}
/// Locks a std mutex, ignoring poisoning: every guarded value is replaced
@@ -437,6 +446,8 @@ impl Client {
server_time_offset: AtomicI64::new(0),
tasks: TaskTracker::new(),
background: CancellationToken::new(),
+ connection_parent: Mutex::new(tracing::Span::none()),
+ pending_login: Mutex::new(None),
})
}
@@ -450,7 +461,40 @@ impl Client {
where
Task: Future<Output = ()> + Send + 'static,
{
- self.tasks.spawn(task);
+ // Macro addition: background work stays in the caller's trace.
+ self.tasks.spawn(task.in_current_span());
+ }
+
+ /// Macro addition: the span connection work nests under.
+ pub(crate) fn connection_parent(&self) -> tracing::Span {
+ lock(&self.connection_parent).clone()
+ }
+
+ /// Macro addition: a `whatsmeow.connect` span under the connection's
+ /// parent span.
+ fn connect_span(&self, reason: ConnectReason, attempt: u32) -> tracing::Span {
+ tracing::info_span!(
+ parent: &self.connection_parent(),
+ "whatsmeow.connect",
+ reason = reason.as_str(),
+ attempt,
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ )
+ }
+
+ /// Macro addition: ends the pending login span with an outcome.
+ pub(crate) fn finish_login_span(
+ &self,
+ outcome: &'static str,
+ failed: bool,
+ ) -> Option<tracing::Span> {
+ let span = lock(&self.pending_login).take()?;
+ span.record("outcome", outcome);
+ if failed {
+ crate::telemetry::mark_error(&span);
+ }
+ Some(span)
}
/// Spawns `dispatch_event` in the background (Go's `go cli.dispatchEvent`).
@@ -503,8 +547,27 @@ impl Client {
/// Connects to the WhatsApp web websocket. After connecting, the client
/// either logs in with the stored device or emits [`Event::Qr`] to pair a
/// new one.
- #[tracing::instrument(name = "whatsmeow.connect", skip_all, err)]
pub async fn connect(self: &Arc<Self>) -> Result<(), ClientError> {
+ *lock(&self.connection_parent) = tracing::Span::current();
+ self.connect_with_reason(ConnectReason::Initial).await
+ }
+
+ /// Macro addition: [`Client::connect`] in a `whatsmeow.connect` span
+ /// recording why it connects.
+ pub(crate) async fn connect_with_reason(
+ self: &Arc<Self>,
+ reason: ConnectReason,
+ ) -> Result<(), ClientError> {
+ let span = self.connect_span(reason, 0);
+ let result = self.connect_untraced().instrument(span.clone()).await;
+ if let Err(error) = &result {
+ tracing::warn!(parent: &span, error = %error, "connect failed");
+ }
+ crate::telemetry::record_result(&span, &result);
+ result
+ }
+
+ async fn connect_untraced(self: &Arc<Self>) -> Result<(), ClientError> {
let mut state = self.socket.write().await;
let result = self.unlocked_connect(&mut state).await;
drop(state);
@@ -516,7 +579,7 @@ impl Client {
tracing::error!(error = %error, "initial connection failed but reconnecting in background");
self.spawn_dispatch(Event::Disconnected(Disconnected));
let client = Arc::clone(self);
- self.spawn(async move { client.auto_reconnect().await });
+ self.spawn(async move { client.auto_reconnect(ConnectReason::ConnectFailed).await });
return Ok(());
}
result
@@ -552,7 +615,19 @@ impl Client {
}
self.reset_expected_disconnect();
- let (frame_socket, frames) = self.config.dialer.dial().await?;
+ let dial_span = tracing::info_span!(
+ "whatsmeow.connect.dial",
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ let dialed = self
+ .config
+ .dialer
+ .dial()
+ .instrument(dial_span.clone())
+ .await;
+ crate::telemetry::record_result(&dial_span, &dialed);
+ let (frame_socket, frames) = dialed?;
let (noise_key, client_payload) = {
let store = self.store.read().await;
let payload = store.get_client_payload().map_err(|error| {
@@ -567,7 +642,12 @@ impl Client {
return Err(error);
}
};
- let (noise_socket, noise_events) = match do_handshake(
+ let handshake_span = tracing::info_span!(
+ "whatsmeow.connect.handshake",
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ let handshake = do_handshake(
frame_socket.clone(),
frames,
&new_key_pair(),
@@ -575,14 +655,23 @@ impl Client {
&client_payload,
self.signatures(),
)
- .await
- {
+ .instrument(handshake_span.clone())
+ .await;
+ crate::telemetry::record_result(&handshake_span, &handshake);
+ let (noise_socket, noise_events) = match handshake {
Ok(result) => result,
Err(error) => {
frame_socket.close(None).await;
return Err(error.into());
}
};
+ // Ended by the server's `success` or `failure` node, or a disconnect.
+ *lock(&self.pending_login) = Some(tracing::info_span!(
+ "whatsmeow.connect.login",
+ outcome = tracing::field::Empty,
+ failure_reason = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ ));
let noise_socket = Arc::new(noise_socket);
let connection = CancellationToken::new();
let (queue_sender, queue_receiver) = mpsc::channel(HANDLER_QUEUE_SIZE);
@@ -591,22 +680,34 @@ impl Client {
state.connection = Some(connection.clone());
state.handler_queue_wait = Some(close_wait_receiver);
+ // Macro addition: the connection's loops run under the caller's span,
+ // not the connect span, so received nodes nest under the caller.
+ let parent = self.connection_parent();
let client = Arc::clone(self);
let reader_connection = connection.clone();
- self.spawn(async move {
- client
- .read_loop(noise_socket, noise_events, queue_sender, reader_connection)
- .await;
- });
+ self.spawn(
+ async move {
+ client
+ .read_loop(noise_socket, noise_events, queue_sender, reader_connection)
+ .await;
+ }
+ .instrument(parent.clone()),
+ );
let client = Arc::clone(self);
let keepalive_connection = connection.clone();
- self.spawn(async move { client.keep_alive_loop(keepalive_connection).await });
+ self.spawn(
+ async move { client.keep_alive_loop(keepalive_connection).await }
+ .instrument(parent.clone()),
+ );
let client = Arc::clone(self);
- self.spawn(async move {
- client
- .handler_queue_loop(connection, queue_receiver, close_wait_sender)
- .await;
- });
+ self.spawn(
+ async move {
+ client
+ .handler_queue_loop(connection, queue_receiver, close_wait_sender)
+ .await;
+ }
+ .instrument(parent),
+ );
Ok(())
}
@@ -651,13 +752,19 @@ impl Client {
{
state.socket = None;
self.clear_response_waiters(&xml_stream_end_node());
+ self.finish_login_span("disconnected", true);
if !self.is_expected_disconnect()
&& (self.force_auto_reconnect.swap(false, Ordering::SeqCst) || remote)
{
tracing::debug!("emitting Disconnected event");
self.spawn_dispatch(Event::Disconnected(Disconnected));
+ let reason = if remote {
+ ConnectReason::NetworkDrop
+ } else {
+ ConnectReason::ForcedReset
+ };
let client = Arc::clone(self);
- self.spawn(async move { client.auto_reconnect().await });
+ self.spawn(async move { client.auto_reconnect(reason).await });
} else if remote {
tracing::debug!("on_disconnect called, but it was expected, so not emitting event");
} else {
@@ -685,14 +792,16 @@ impl Client {
/// Boxed with an explicit `Send` bound: reconnecting calls back into
/// `connect`, whose tasks can start another reconnect, and the compiler
/// can't infer `Send` through that cycle.
- pub(crate) fn auto_reconnect(self: Arc<Self>) -> BoxFuture<'static, ()> {
- Box::pin(self.auto_reconnect_inner())
+ /// `reason` (a Macro addition) labels the reconnect's spans.
+ pub(crate) fn auto_reconnect(self: Arc<Self>, reason: ConnectReason) -> BoxFuture<'static, ()> {
+ Box::pin(self.auto_reconnect_inner(reason))
}
- async fn auto_reconnect_inner(self: Arc<Self>) {
+ async fn auto_reconnect_inner(self: Arc<Self>, reason: ConnectReason) {
if !self.config.enable_auto_reconnect || self.store.read().await.id.is_none() {
return;
}
+ tracing::info!(parent: &self.connection_parent(), reason = reason.as_str(), "connection lost, reconnecting");
loop {
let errors = self.auto_reconnect_errors.fetch_add(1, Ordering::SeqCst);
let delay = Duration::from_secs(u64::from(errors) * 2);
@@ -708,7 +817,12 @@ impl Client {
}
() = tokio::time::sleep(delay) => {}
}
- match self.connect_inner().await {
+ let span = self.connect_span(reason, errors + 1);
+ let result = self.connect_inner().instrument(span.clone()).await;
+ if !matches!(result, Err(ClientError::AlreadyConnected)) {
+ crate::telemetry::record_result(&span, &result);
+ }
+ match result {
Err(ClientError::AlreadyConnected) => {
tracing::debug!(
"connect said we're already connected after autoreconnect sleep"
@@ -935,13 +1049,16 @@ impl Client {
let tag = node.tag.clone();
let client = Arc::clone(&self);
let start = tokio::time::Instant::now();
- let mut handler = self.tasks.spawn(async move {
- client.handle_node(node).await;
- let duration = start.elapsed();
- if duration > Duration::from_secs(5) {
- tracing::warn!(duration = ?duration, "node handling took long");
+ let mut handler = self.tasks.spawn(
+ async move {
+ client.handle_node(node).await;
+ let duration = start.elapsed();
+ if duration > Duration::from_secs(5) {
+ tracing::warn!(duration = ?duration, "node handling took long");
+ }
}
- });
+ .in_current_span(),
+ );
for _ in 0..10 {
tokio::select! {
_ = &mut handler => continue 'nodes,
diff --git a/crates/whatsmeow/src/connectionevents.rs b/crates/whatsmeow/src/connectionevents.rs
index c526376c89..251cb44209 100644
--- a/crates/whatsmeow/src/connectionevents.rs
+++ b/crates/whatsmeow/src/connectionevents.rs
@@ -14,6 +14,7 @@ use std::sync::atomic::Ordering;
use std::time::Duration;
use chrono::Utc;
+use tracing::Instrument;
use crate::binary::{Node, NodeContent};
use crate::client::Client;
@@ -21,6 +22,7 @@ use crate::errors::ClientError;
use crate::prekeys::MIN_PRE_KEY_COUNT;
use crate::request::{InfoQuery, IqType};
use crate::store::get_wa_version;
+use crate::telemetry::ConnectReason;
use crate::types::events::{
ClientOutdated, ConnectFailure, ConnectFailureReason, Connected, Event, LoggedOut,
ManualLoginReconnect, OfflineSyncCompleted, OfflineSyncPreview, QrScannedWithoutMultidevice,
@@ -32,6 +34,8 @@ impl Client {
pub(crate) async fn handle_stream_error(self: &Arc<Self>, node: &Node) {
self.set_logged_in(false);
self.clear_response_waiters(node);
+ // A 515 restart (after pairing) is expected, not a failed login.
+ self.finish_login_span("stream_error", code_is_not_515(node));
let code = node
.attrs
.get("code")
@@ -50,17 +54,21 @@ impl Client {
.await;
return;
}
- tracing::info!("got 515 code, reconnecting");
+ tracing::info!(
+ disconnect_reason = ConnectReason::Restart515.as_str(),
+ "got 515 code, reconnecting"
+ );
let client = Arc::clone(self);
self.spawn(async move {
client.disconnect().await;
- if let Err(error) = client.connect().await {
+ if let Err(error) = client.connect_with_reason(ConnectReason::Restart515).await {
tracing::error!(error = %error, "failed to reconnect after 515 code");
}
});
} else if code == "401" && conflict_type == "device_removed" {
self.expect_disconnect();
tracing::info!(
+ disconnect_reason = "logged_out",
"got device removed stream error, sending LoggedOut event and deleting session"
);
self.spawn_dispatch(Event::LoggedOut(LoggedOut {
@@ -72,7 +80,10 @@ impl Client {
}
} else if conflict_type == "replaced" {
self.expect_disconnect();
- tracing::info!("got replaced stream error, sending StreamReplaced event");
+ tracing::info!(
+ disconnect_reason = "conflict_replaced",
+ "got replaced stream error, sending StreamReplaced event"
+ );
self.spawn_dispatch(Event::StreamReplaced(StreamReplaced));
} else if code == "503" {
// The server wants to restart; the disconnect is emitted as
@@ -122,6 +133,9 @@ impl Client {
let mut attrs = node.attr_getter();
let reason = ConnectFailureReason(attrs.int("reason"));
let message = attrs.optional_string("message");
+ if let Some(login) = self.finish_login_span("failure", true) {
+ login.record("failure_reason", reason.0);
+ }
let will_auto_reconnect = reason == ConnectFailureReason::SERVICE_UNAVAILABLE
|| reason == ConnectFailureReason::INTERNAL_SERVER_ERROR
|| reason == ConnectFailureReason::CAT_INVALID
@@ -134,7 +148,7 @@ impl Client {
tracing::debug!("got 403 connect failure");
}
if reason.is_logged_out() {
- tracing::info!(reason = %reason, "got logged out connect failure, sending LoggedOut event and deleting session");
+ tracing::info!(reason = %reason, disconnect_reason = "logged_out", "got logged out connect failure, sending LoggedOut event and deleting session");
self.spawn_dispatch(Event::LoggedOut(LoggedOut {
on_connect: true,
reason,
@@ -173,6 +187,11 @@ impl Client {
}
tracing::info!("successfully authenticated");
self.mark_connect_success();
+ // Macro addition: the login span covers the post-login requests
+ // below and ends when `Connected` is dispatched.
+ let login = crate::client::lock(&self.pending_login)
+ .take()
+ .unwrap_or_else(tracing::Span::current);
let mut attrs = node.attr_getter();
let node_lid = attrs.jid("lid");
if let Some(server_time) = attrs.unix_time("t") {
@@ -237,7 +256,9 @@ impl Client {
}
client.dispatch_event(Event::Connected(Connected)).await;
client.close_socket_wait_chan();
- });
+ tracing::Span::current().record("outcome", "ok");
+ }
+ .instrument(login));
}
/// Tells the server whether this device is passive. The client sends
@@ -258,3 +279,10 @@ impl Client {
.map(|_| ())
}
}
+
+/// Macro addition: whether a stream error isn't the 515 restart.
+fn code_is_not_515(node: &Node) -> bool {
+ node.attrs
+ .get("code")
+ .is_none_or(|code| code.to_string() != "515")
+}
diff --git a/crates/whatsmeow/src/download.rs b/crates/whatsmeow/src/download.rs
index 65ef6ba1f4..ab6c76e0ec 100644
--- a/crates/whatsmeow/src/download.rs
+++ b/crates/whatsmeow/src/download.rs
@@ -25,6 +25,7 @@ use base64::engine::general_purpose::URL_SAFE;
use chrono::{NaiveDateTime, Utc};
use hmac::{Hmac, Mac};
use sha2::{Digest, Sha256};
+use tracing::Instrument;
use crate::mediaconn::MediaConn;
use crate::proto::wa_e2e::{
@@ -546,6 +547,8 @@ pub async fn download_media_with_path(
Ok(data)
}
+/// Macro addition: a `whatsmeow.media.fetch` span per host tried, with the
+/// size, retries and hash check outcome.
async fn download_and_decrypt(
http: &MediaHttpClient,
url: &str,
@@ -553,6 +556,44 @@ async fn download_and_decrypt(
app_info: Option<MediaType>,
file_enc_sha256: Option<&[u8]>,
file_sha256: Option<&[u8]>,
+) -> Result<Vec<u8>, DownloadError> {
+ let span = tracing::info_span!(
+ "whatsmeow.media.fetch",
+ encrypted = media_key.is_some() || file_enc_sha256.is_some(),
+ size = tracing::field::Empty,
+ retries = tracing::field::Empty,
+ hash_check = tracing::field::Empty,
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ let result =
+ download_and_decrypt_untraced(http, url, media_key, app_info, file_enc_sha256, file_sha256)
+ .instrument(span.clone())
+ .await;
+ let hash_check = match &result {
+ Ok(data) => {
+ span.record("size", data.len());
+ "ok"
+ }
+ Err(DownloadError::InvalidMediaEncSha256) => "enc_sha256_mismatch",
+ Err(DownloadError::InvalidMediaHmac) => "hmac_mismatch",
+ Err(DownloadError::InvalidMediaSha256 | DownloadError::InvalidUnencryptedMediaSha256) => {
+ "sha256_mismatch"
+ }
+ Err(_) => "not_checked",
+ };
+ span.record("hash_check", hash_check);
+ crate::telemetry::record_result(&span, &result);
+ result
+}
+
+async fn download_and_decrypt_untraced(
+ http: &MediaHttpClient,
+ url: &str,
+ media_key: Option<&[u8]>,
+ app_info: Option<MediaType>,
+ file_enc_sha256: Option<&[u8]>,
+ file_sha256: Option<&[u8]>,
) -> Result<Vec<u8>, DownloadError> {
let keys = get_media_keys(media_key.unwrap_or_default(), app_info);
let (ciphertext, mac) =
@@ -659,6 +700,7 @@ async fn download_possibly_encrypted_media_with_retries(
);
tokio::time::sleep(retry_duration).await;
retry_num += 1;
+ tracing::Span::current().record("retries", retry_num);
if retry_num == 5 {
return Err(error);
}
@@ -765,7 +807,12 @@ fn retry_after_parse(retry_after: &str, fallback: Duration) -> Duration {
impl crate::client::Client {
/// Downloads and decrypts the attachment of a message part (e.g. its
/// `image_message`), checking its hashes (`Download`).
- #[tracing::instrument(name = "whatsmeow.download", skip_all, err)]
+ #[tracing::instrument(
+ name = "whatsmeow.download",
+ skip_all,
+ fields(media_type = ?get_media_type(msg)),
+ err
+ )]
pub async fn download(
&self,
msg: &(dyn DownloadableMessage + Sync),
@@ -782,6 +829,12 @@ impl crate::client::Client {
clippy::too_many_arguments,
reason = "mirrors Go's DownloadMediaWithPath"
)]
+ #[tracing::instrument(
+ name = "whatsmeow.download",
+ skip_all,
+ fields(media_type = ?media_type, mms_type = mms_type),
+ err
+ )]
pub async fn download_media_with_path(
&self,
direct_path: &str,
diff --git a/crates/whatsmeow/src/keepalive.rs b/crates/whatsmeow/src/keepalive.rs
index 752024e1a5..b249ec1db5 100644
--- a/crates/whatsmeow/src/keepalive.rs
+++ b/crates/whatsmeow/src/keepalive.rs
@@ -58,7 +58,11 @@ impl Client {
self.disconnect().await;
self.reset_expected_disconnect();
let client = Arc::clone(&self);
- self.spawn(async move { client.auto_reconnect().await });
+ self.spawn(async move {
+ client
+ .auto_reconnect(crate::telemetry::ConnectReason::KeepaliveTimeout)
+ .await;
+ });
}
} else {
if error_count > 0 {
diff --git a/crates/whatsmeow/src/lib.rs b/crates/whatsmeow/src/lib.rs
index e5ff7d85d1..4c0aa797d5 100644
--- a/crates/whatsmeow/src/lib.rs
+++ b/crates/whatsmeow/src/lib.rs
@@ -44,6 +44,7 @@ pub mod signal;
pub mod socket;
pub mod store;
mod tctoken;
+mod telemetry;
#[cfg(any(test, feature = "testing"))]
pub mod testing;
pub mod types;
diff --git a/crates/whatsmeow/src/message.rs b/crates/whatsmeow/src/message.rs
index dde3f3d9d7..c7d57904db 100644
--- a/crates/whatsmeow/src/message.rs
+++ b/crates/whatsmeow/src/message.rs
@@ -25,6 +25,7 @@ use async_trait::async_trait;
use chrono::{DateTime, Utc};
use prost::Message as _;
use sha2::{Digest, Sha256};
+use tracing::Instrument;
use crate::binary::{Node, NodeContent};
use crate::client::Client;
@@ -373,14 +374,29 @@ impl Client {
#[tracing::instrument(
name = "whatsmeow.receive_message",
skip_all,
- fields(message_id = %info.id, is_group = info.is_group, enc_count)
+ fields(
+ message_id = %info.id,
+ is_group = info.is_group,
+ enc_count,
+ decrypted,
+ decrypt_failed,
+ retry_receipt,
+ ack_ms,
+ outcome,
+ otel.status_code,
+ )
)]
async fn decrypt_messages(self: &Arc<Self>, info: &mut MessageInfo, node: &Node) {
+ // Macro addition: counts and ack latency on this span.
+ let received = tokio::time::Instant::now();
+ let receive_span = tracing::Span::current();
+ let mut decrypted_count = 0_usize;
if let Some(unavailable) = node.get_optional_child_by_tag(&["unavailable"])
&& node.get_children_by_tag("enc").next().is_none()
{
let unavailable_type = UnavailableType::from(unavailable.attr_getter().string("type"));
tracing::warn!(unavailable_type = %unavailable_type, "unavailable message");
+ receive_span.record("outcome", "unavailable");
let client = Arc::clone(self);
let ack_info = info.clone();
let ack_node = node.clone();
@@ -431,6 +447,12 @@ impl Client {
let Some(enc_type) = attrs.get_string("type", false) else {
continue;
};
+ let decrypt_span = tracing::debug_span!(
+ "whatsmeow.decrypt",
+ enc_type = %enc_type,
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
let result = if enc_type == "pkmsg" || enc_type == "msg" {
contains_direct_msg = true;
self.decrypt_dm(
@@ -439,14 +461,17 @@ impl Client {
enc_type == "pkmsg",
info.timestamp,
)
+ .instrument(decrypt_span.clone())
.await
} else if info.is_group && enc_type == "skmsg" {
self.decrypt_group_msg(child, &sender_encryption_jid, &info.chat, info.timestamp)
+ .instrument(decrypt_span.clone())
.await
} else {
tracing::warn!(enc_type = %enc_type, "unhandled encrypted message type");
continue;
};
+ record_decrypt_outcome(&decrypt_span, &receive_span, &result, &mut decrypted_count);
let (decrypted, ciphertext_hash) = match result {
Err(DecryptError::AlreadyProcessed(_)) => {
tracing::debug!("ignoring already processed message");
@@ -461,18 +486,22 @@ impl Client {
let is_unavailable = enc_type == "skmsg"
&& !contains_direct_msg
&& matches!(error.signal(), Some(SignalError::NoSenderKeyForUser));
+ receive_span.record("retry_receipt", true);
if self.config.synchronous_ack {
self.send_retry_receipt(node, info, is_unavailable).await;
self.send_ack(node, 0).await;
+ record_ack_latency(&receive_span, received);
} else {
let client = Arc::clone(self);
let retry_node = node.clone();
let retry_info = info.clone();
+ let ack_span = receive_span.clone();
self.spawn(async move {
client
.send_retry_receipt(&retry_node, &retry_info, is_unavailable)
.await;
client.send_ack(&retry_node, 0).await;
+ record_ack_latency(&ack_span, received);
});
}
self.dispatch_event(Event::UndecryptableMessage(UndecryptableMessage {
@@ -528,9 +557,20 @@ impl Client {
self.maybe_delete_old_buffered_hashes(event_buffer).await;
}
}
+ receive_span.record(
+ "outcome",
+ if !recognized_stanza {
+ "unrecognized"
+ } else if protobuf_failed {
+ "invalid_protobuf"
+ } else {
+ "ok"
+ },
+ );
let client = Arc::clone(self);
let receipt_info = info.clone();
let receipt_node = node.clone();
+ let ack_span = receive_span.clone();
self.background_if_async_ack(async move {
if !recognized_stanza {
client
@@ -543,6 +583,7 @@ impl Client {
.send_message_receipt(&receipt_info, &receipt_node)
.await;
}
+ record_ack_latency(&ack_span, received);
})
.await;
}
@@ -834,9 +875,25 @@ impl Client {
let Some(notification) = notification else {
break;
};
+ // Macro addition: one span per history sync notification.
+ let span = tracing::info_span!(
+ "whatsmeow.history_sync.process",
+ sync_type = notification.sync_type,
+ chunk_order = notification.chunk_order,
+ conversations = tracing::field::Empty,
+ outcome = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ async {
match self.download_history_sync(&notification, false).await {
- Err(error) => tracing::error!(error = %error, "failed to download history sync"),
+ Err(error) => {
+ tracing::error!(error = %error, "failed to download history sync");
+ tracing::Span::current().record("outcome", "error");
+ crate::telemetry::mark_error(&tracing::Span::current());
+ }
Ok(blob) => {
+ tracing::Span::current().record("conversations", blob.conversations.len());
+ tracing::Span::current().record("outcome", "ok");
self.dispatch_event(Event::HistorySync(Box::new(HistorySync {
data: blob,
notification: notification.clone(),
@@ -855,6 +912,9 @@ impl Client {
}
}
}
+ }
+ .instrument(span)
+ .await;
}
self.history_sync_handler_started
.store(false, Ordering::SeqCst);
@@ -874,7 +934,11 @@ impl Client {
"new history sync notifications appeared after loop stopped, restarting loop"
);
let client = Arc::clone(&self);
- self.spawn(client.handle_history_sync_notification_loop());
+ self.spawn(
+ client
+ .handle_history_sync_notification_loop()
+ .instrument(self.connection_parent()),
+ );
}
}
@@ -981,13 +1045,14 @@ impl Client {
continue;
}
};
- match self.parse_web_message(&Jid::default(), web_message).await {
+ match Box::pin(self.parse_web_message(&Jid::default(), web_message)).await {
Err(error) => {
tracing::warn!(error = %error, item = index + 1, "failed to parse web message info in placeholder resend item");
}
Ok(mut event) => {
event.unavailable_request_id = request_id.clone();
- ok = !self.dispatch_event(Event::Message(Box::new(event))).await && ok;
+ ok =
+ !Box::pin(self.dispatch_event(Event::Message(Box::new(event)))).await && ok;
}
}
}
@@ -1016,7 +1081,11 @@ impl Client {
.is_ok()
{
let client = Arc::clone(self);
- self.spawn(client.handle_history_sync_notification_loop());
+ self.spawn(
+ client
+ .handle_history_sync_notification_loop()
+ .instrument(self.connection_parent()),
+ );
}
}
if !(self.config.manual_history_sync_download
@@ -1050,7 +1119,10 @@ impl Client {
{
let request_type = response.peer_data_operation_request_type;
if request_type == Some(PeerDataOperationRequestType::PlaceholderMessageResend as i32) {
- ok = self.handle_placeholder_resend_response(response).await && ok;
+ // Boxed (Macro addition): parsing and dispatching the resent
+ // message nests deep in decryption; inline it overflows a
+ // 2 MiB stack in debug builds.
+ ok = Box::pin(self.handle_placeholder_resend_response(response)).await && ok;
} else if request_type
== Some(PeerDataOperationRequestType::CompanionSyncdSnapshotFatalRecovery as i32)
{
@@ -1493,5 +1565,43 @@ pub fn pad_message(mut plaintext: Vec<u8>) -> Vec<u8> {
plaintext
}
+/// Macro addition: records a decrypt's outcome on its debug span and counts
+/// it on the message's receive span.
+fn record_decrypt_outcome<Value>(
+ decrypt_span: &tracing::Span,
+ receive_span: &tracing::Span,
+ result: &Result<Value, DecryptError>,
+ decrypted_count: &mut usize,
+) {
+ let outcome = match result {
+ Ok(_) => {
+ *decrypted_count += 1;
+ receive_span.record("decrypted", *decrypted_count);
+ "ok"
+ }
+ Err(DecryptError::AlreadyProcessed(_)) => "already_processed",
+ Err(error) if matches!(error.signal(), Some(SignalError::OldCounter)) => "old_counter",
+ Err(error) if matches!(error.signal(), Some(SignalError::NoSenderKeyForUser)) => {
+ "no_sender_key"
+ }
+ Err(_) => "error",
+ };
+ decrypt_span.record("outcome", outcome);
+ if matches!(outcome, "error" | "no_sender_key") {
+ crate::telemetry::mark_error(decrypt_span);
+ receive_span.record("decrypt_failed", true);
+ receive_span.record("outcome", "decrypt_failed");
+ crate::telemetry::mark_error(receive_span);
+ }
+}
+
+/// Macro addition: the time from handling a message to acking it.
+fn record_ack_latency(span: &tracing::Span, received: tokio::time::Instant) {
+ span.record(
+ "ack_ms",
+ u64::try_from(received.elapsed().as_millis()).unwrap_or(u64::MAX),
+ );
+}
+
#[cfg(test)]
mod test;
diff --git a/crates/whatsmeow/src/prekeys.rs b/crates/whatsmeow/src/prekeys.rs
index 161447dabc..ed283a3157 100644
--- a/crates/whatsmeow/src/prekeys.rs
+++ b/crates/whatsmeow/src/prekeys.rs
@@ -66,6 +66,11 @@ impl Client {
}
/// Uploads a batch of prekeys (812 on the first upload after pairing).
+ #[tracing::instrument(
+ name = "whatsmeow.prekeys.upload",
+ skip_all,
+ fields(initial = initial_upload, count, outcome, otel.status_code)
+ )]
pub(crate) async fn upload_pre_keys(&self, initial_upload: bool) {
let mut last_upload = self.upload_pre_keys_lock.lock().await;
if let Some(last) = *last_upload
@@ -74,6 +79,7 @@ impl Client {
let server_count = self.get_server_pre_key_count().await.unwrap_or_default();
if server_count >= usize::try_from(WANTED_PRE_KEY_COUNT).unwrap_or(usize::MAX) {
tracing::debug!("canceling prekey upload request due to likely race condition");
+ tracing::Span::current().record("outcome", "skipped");
return;
}
}
@@ -95,6 +101,8 @@ impl Client {
Ok(pre_keys) => pre_keys,
Err(error) => {
tracing::error!(error = %error, "failed to get prekeys to upload");
+ tracing::Span::current().record("outcome", "store_error");
+ crate::telemetry::mark_error(&tracing::Span::current());
return;
}
};
@@ -103,6 +111,7 @@ impl Client {
return;
};
tracing::info!(count = pre_keys.len(), "uploading new prekeys to server");
+ tracing::Span::current().record("count", pre_keys.len());
let result = self
.send_iq(InfoQuery {
namespace: "encrypt",
@@ -124,9 +133,12 @@ impl Client {
.await;
if let Err(error) = result {
tracing::error!(error = %error, "failed to send request to upload prekeys");
+ tracing::Span::current().record("outcome", "error");
+ crate::telemetry::mark_error(&tracing::Span::current());
return;
}
tracing::debug!("got response to uploading prekeys");
+ tracing::Span::current().record("outcome", "ok");
if let Err(error) = pre_key_store.mark_pre_keys_as_uploaded(last_key_id).await {
tracing::warn!(error = %error, "failed to mark prekeys as uploaded");
return;
diff --git a/crates/whatsmeow/src/request.rs b/crates/whatsmeow/src/request.rs
index 3adbde3796..0d98c931f5 100644
--- a/crates/whatsmeow/src/request.rs
+++ b/crates/whatsmeow/src/request.rs
@@ -12,6 +12,7 @@
use std::time::Duration;
use tokio::sync::oneshot;
+use tracing::Instrument;
use crate::binary::{Attrs, Node, NodeContent};
use crate::client::Client;
@@ -152,13 +153,24 @@ impl Client {
/// Sends an info query and waits for the response; an error response is
/// an [`IqError`]. A disconnect before the response retries once after
/// reconnecting, unless `no_retry` is set.
- #[tracing::instrument(
- name = "whatsmeow.iq",
- skip_all,
- fields(xmlns = query.namespace, iq_type = %query.r#type),
- err
- )]
- pub(crate) async fn send_iq(&self, mut query: InfoQuery) -> Result<Node, ClientError> {
+ pub(crate) async fn send_iq(&self, query: InfoQuery) -> Result<Node, ClientError> {
+ // Macro addition: one span per info query with its outcome. Not
+ // `err`: an IQ error's message can hold the raw response node.
+ let span = tracing::info_span!(
+ "whatsmeow.iq",
+ xmlns = query.namespace,
+ iq_type = %query.r#type,
+ kind = crate::telemetry::iq_kind(query.content.as_ref()),
+ outcome = tracing::field::Empty,
+ error_code = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ let result = self.send_iq_inner(query).instrument(span.clone()).await;
+ crate::telemetry::record_iq_result(&span, &result);
+ result
+ }
+
+ async fn send_iq_inner(&self, mut query: InfoQuery) -> Result<Node, ClientError> {
if query.timeout.is_zero() {
query.timeout = DEFAULT_REQUEST_TIMEOUT;
}
diff --git a/crates/whatsmeow/src/retry.rs b/crates/whatsmeow/src/retry.rs
index dde318a026..0d6053ac4d 100644
--- a/crates/whatsmeow/src/retry.rs
+++ b/crates/whatsmeow/src/retry.rs
@@ -439,7 +439,10 @@ impl Client {
/// decrypt.
pub(crate) async fn immediate_request_message_from_phone(self: &Arc<Self>, info: &MessageInfo) {
let request = self.build_unavailable_message_request(&info.chat, &info.sender, &info.id);
- match self.send_peer_message(request).await {
+ // Boxed (Macro addition): the send future is large, and this runs
+ // nested in message decryption; inline it overflows a 2 MiB stack in
+ // debug builds.
+ match Box::pin(self.send_peer_message(request)).await {
Err(error) => {
tracing::warn!(error = %error, "failed to send request for unavailable message to phone")
}
@@ -454,6 +457,7 @@ impl Client {
}
/// Sends a retry receipt for an incoming message that didn't decrypt.
+ #[tracing::instrument(name = "whatsmeow.retry_receipt.send", skip_all, fields(retry_count))]
pub(crate) async fn send_retry_receipt(
self: &Arc<Self>,
node: &Node,
@@ -481,6 +485,7 @@ impl Client {
}
*count
};
+ tracing::Span::current().record("retry_count", retry_count);
if retry_count >= 5 {
tracing::warn!("not sending any more retry receipts");
return;
diff --git a/crates/whatsmeow/src/send.rs b/crates/whatsmeow/src/send.rs
index cf243cffa7..0c01e0f1ee 100644
--- a/crates/whatsmeow/src/send.rs
+++ b/crates/whatsmeow/src/send.rs
@@ -125,7 +125,7 @@ impl Client {
#[tracing::instrument(
name = "whatsmeow.send_message",
skip_all,
- fields(message_id, is_group = to.server == GROUP_SERVER, peer = extra.peer),
+ fields(message_id, is_group = to.server == GROUP_SERVER, peer = extra.peer, devices),
err
)]
pub async fn send_message(
@@ -784,6 +784,8 @@ impl Client {
.instrument(tracing::info_span!("whatsmeow.send_message.get_devices"))
.await
.map_err(|error| error.wrap("failed to get device list"))?;
+ // Macro addition: the fan-out on the `whatsmeow.send_message` span.
+ tracing::Span::current().record("devices", all_devices.len());
if to.server == GROUP_SERVER {
all_devices
.retain(|jid| jid.server != HOSTED_SERVER && jid.server != HOSTED_LID_SERVER);
diff --git a/crates/whatsmeow/src/telemetry.rs b/crates/whatsmeow/src/telemetry.rs
new file mode 100644
index 0000000000..00146b86ab
--- /dev/null
+++ b/crates/whatsmeow/src/telemetry.rs
@@ -0,0 +1,100 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// A Macro addition with no whatsmeow counterpart.
+
+//! Helpers for the tracing spans this port adds to whatsmeow's flows. Span
+//! fields hold kinds, counts and outcomes only: never JIDs, phone numbers,
+//! message content or keys.
+
+use tracing::Span;
+
+use crate::binary::Node;
+use crate::errors::ClientError;
+
+/// Why the client is (re)connecting: the `reason` of a `whatsmeow.connect`
+/// span.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::IntoStaticStr)]
+pub(crate) enum ConnectReason {
+ /// [`crate::client::Client::connect`].
+ #[strum(serialize = "initial")]
+ Initial,
+ /// The server's 515 stream error (restart, e.g. after pairing).
+ #[strum(serialize = "restart_515")]
+ Restart515,
+ /// The websocket closed from the other side.
+ #[strum(serialize = "network_drop")]
+ NetworkDrop,
+ /// [`crate::client::Client::reset_connection`].
+ #[strum(serialize = "forced_reset")]
+ ForcedReset,
+ /// Keepalive pings failed for too long.
+ #[strum(serialize = "keepalive_timeout")]
+ KeepaliveTimeout,
+ /// The initial connect failed with a retryable error.
+ #[strum(serialize = "connect_failed")]
+ ConnectFailed,
+}
+
+impl ConnectReason {
+ pub(crate) fn as_str(self) -> &'static str {
+ self.into()
+ }
+}
+
+/// Marks a span as failed; the span must declare `otel.status_code`.
+pub(crate) fn mark_error(span: &Span) {
+ span.record("otel.status_code", "ERROR");
+}
+
+/// Records `outcome` (`ok` or `error`) and the error status of a span that
+/// declares both fields.
+pub(crate) fn record_result<Value, Error>(span: &Span, result: &Result<Value, Error>) {
+ match result {
+ Ok(_) => {
+ span.record("outcome", "ok");
+ }
+ Err(_) => {
+ span.record("outcome", "error");
+ mark_error(span);
+ }
+ }
+}
+
+/// Records the outcome of an info query on its `whatsmeow.iq` span:
+/// `ok`, `timeout`, `disconnected`, or `error` with the IQ `error_code`.
+pub(crate) fn record_iq_result(span: &Span, result: &Result<Node, ClientError>) {
+ let error = match result {
+ Ok(_) => {
+ span.record("outcome", "ok");
+ return;
+ }
+ Err(error) => error.innermost(),
+ };
+ let outcome = match error {
+ ClientError::IqTimedOut => "timeout",
+ ClientError::Disconnected(_) | ClientError::NotConnected => "disconnected",
+ ClientError::Iq(iq) => {
+ span.record("error_code", iq.code);
+ "error"
+ }
+ _ => "failed",
+ };
+ span.record("outcome", outcome);
+ mark_error(span);
+}
+
+/// The tag of an info query's first child, which names the request (e.g.
+/// `query`, `count`, `participants`).
+pub(crate) fn iq_kind(content: Option<&crate::binary::NodeContent>) -> &str {
+ match content {
+ Some(crate::binary::NodeContent::Nodes(children)) => {
+ children.first().map_or("", |child| child.tag.as_str())
+ }
+ _ => "",
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/whatsmeow/src/telemetry/test.rs b/crates/whatsmeow/src/telemetry/test.rs
new file mode 100644
index 0000000000..b4c47bcf71
--- /dev/null
+++ b/crates/whatsmeow/src/telemetry/test.rs
@@ -0,0 +1,240 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+//! The connect and info query spans, captured from a client talking to the
+//! fake server.
+
+use std::cell::RefCell;
+use std::fmt::Debug;
+use std::sync::{Arc, Once};
+
+use tracing::field::{Field, Visit};
+use tracing::span::{Attributes, Id, Record};
+use tracing::{Instrument, Subscriber};
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::{Context, SubscriberExt};
+use tracing_subscriber::registry::LookupSpan;
+
+use crate::client::test::{connect_paired, harness, next_node};
+use crate::errors::ClientError;
+
+#[derive(Debug)]
+struct CapturedSpan {
+ name: &'static str,
+ /// Parent first, root last.
+ ancestors: Vec<&'static str>,
+ fields: Vec<(String, String)>,
+}
+
+impl CapturedSpan {
+ fn field(&self, name: &str) -> Option<&str> {
+ self.fields
+ .iter()
+ .rev()
+ .find(|(field, _)| field == name)
+ .map(|(_, value)| value.as_str())
+ }
+}
+
+/// What the test thread captured. Thread-local because the subscriber is
+/// global: a scoped `set_default` loses callsites that tests on other
+/// threads register first.
+#[derive(Default)]
+struct Captured {
+ spans: Vec<CapturedSpan>,
+ events: Vec<Vec<(String, String)>>,
+}
+
+thread_local! {
+ static CAPTURED: RefCell<Option<Captured>> = const { RefCell::new(None) };
+}
+
+/// Starts capturing on this thread; returns what was captured when `run`
+/// finishes.
+async fn capture(run: impl Future<Output = ()>) -> Captured {
+ static INSTALL: Once = Once::new();
+ INSTALL.call_once(|| {
+ tracing::subscriber::set_global_default(tracing_subscriber::registry().with(Capture))
+ .expect("no other global subscriber in this test binary");
+ });
+ CAPTURED.with(|captured| *captured.borrow_mut() = Some(Captured::default()));
+ run.await;
+ CAPTURED.with(|captured| captured.borrow_mut().take().expect("capturing"))
+}
+
+struct Capture;
+
+struct SpanIndex(usize);
+
+struct Fields<'fields>(&'fields mut Vec<(String, String)>);
+
+impl Visit for Fields<'_> {
+ fn record_str(&mut self, field: &Field, value: &str) {
+ self.0.push((field.name().to_owned(), value.to_owned()));
+ }
+
+ fn record_debug(&mut self, field: &Field, value: &dyn Debug) {
+ self.0.push((field.name().to_owned(), format!("{value:?}")));
+ }
+}
+
+impl<Inner> Layer<Inner> for Capture
+where
+ Inner: Subscriber + for<'lookup> LookupSpan<'lookup>,
+{
+ fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, context: Context<'_, Inner>) {
+ CAPTURED.with(|captured| {
+ let mut captured = captured.borrow_mut();
+ let Some(captured) = captured.as_mut() else {
+ return;
+ };
+ let span = context.span(id).expect("the new span is registered");
+ let ancestors = span
+ .scope()
+ .skip(1)
+ .map(|ancestor| ancestor.name())
+ .collect();
+ let mut fields = Vec::new();
+ attrs.record(&mut Fields(&mut fields));
+ captured.spans.push(CapturedSpan {
+ name: span.name(),
+ ancestors,
+ fields,
+ });
+ span.extensions_mut()
+ .insert(SpanIndex(captured.spans.len() - 1));
+ });
+ }
+
+ fn on_record(&self, id: &Id, values: &Record<'_>, context: Context<'_, Inner>) {
+ CAPTURED.with(|captured| {
+ let mut captured = captured.borrow_mut();
+ let Some(captured) = captured.as_mut() else {
+ return;
+ };
+ let span = context.span(id).expect("the recorded span is registered");
+ let extensions = span.extensions();
+ if let Some(SpanIndex(index)) = extensions.get::<SpanIndex>() {
+ values.record(&mut Fields(&mut captured.spans[*index].fields));
+ }
+ });
+ }
+
+ fn on_event(&self, event: &tracing::Event<'_>, _context: Context<'_, Inner>) {
+ CAPTURED.with(|captured| {
+ if let Some(captured) = captured.borrow_mut().as_mut() {
+ let mut fields = Vec::new();
+ event.record(&mut Fields(&mut fields));
+ captured.events.push(fields);
+ }
+ });
+ }
+}
+
+#[tokio::test(start_paused = true)]
+async fn connect_and_info_queries_are_traced_without_jids() {
+ let captured = capture(async {
+ let account = tracing::info_span!("account");
+ let mut harness = harness(Some(("1234:[email protected]", "9876:5@lid")));
+ let mut connection = connect_paired(&mut harness)
+ .instrument(account.clone())
+ .await;
+
+ let client = Arc::clone(&harness.client);
+ let failed =
+ tokio::spawn(async move { client.set_passive(true).await }.instrument(account.clone()));
+ let request = next_node(&mut connection).await;
+ connection
+ .respond_iq_error(&request, 500, "internal-server-error")
+ .await;
+ failed.await.unwrap().unwrap_err();
+
+ let client = Arc::clone(&harness.client);
+ let timed_out = tokio::spawn(
+ async move { client.set_passive(false).await }.instrument(account.clone()),
+ );
+ let _ignored = next_node(&mut connection).await;
+ assert!(matches!(
+ timed_out.await.unwrap(),
+ Err(ClientError::IqTimedOut)
+ ));
+ })
+ .await;
+
+ let spans = &captured.spans;
+ let named = |name: &str| -> Vec<&CapturedSpan> {
+ spans.iter().filter(|span| span.name == name).collect()
+ };
+
+ let connect = named("whatsmeow.connect");
+ assert_eq!(connect.len(), 1, "{connect:#?}");
+ assert_eq!(connect[0].ancestors, ["account"]);
+ assert_eq!(connect[0].field("reason"), Some("initial"));
+ assert_eq!(connect[0].field("outcome"), Some("ok"));
+ for phase in [
+ "whatsmeow.connect.dial",
+ "whatsmeow.connect.handshake",
+ "whatsmeow.connect.login",
+ ] {
+ let phase_spans = named(phase);
+ assert_eq!(phase_spans.len(), 1, "{phase}: {phase_spans:#?}");
+ assert_eq!(
+ phase_spans[0].ancestors,
+ ["whatsmeow.connect", "account"],
+ "{phase}"
+ );
+ assert_eq!(phase_spans[0].field("outcome"), Some("ok"), "{phase}");
+ }
+
+ let received = named("whatsmeow.handle_node");
+ assert!(!received.is_empty());
+ for span in &received {
+ assert!(span.ancestors.contains(&"account"), "{span:#?}");
+ }
+
+ let iqs = named("whatsmeow.iq");
+ let login_iqs: Vec<_> = iqs
+ .iter()
+ .filter(|span| span.ancestors.first() == Some(&"whatsmeow.connect.login"))
+ .collect();
+ assert!(
+ login_iqs
+ .iter()
+ .any(|span| span.field("xmlns") == Some("encrypt")
+ && span.field("kind") == Some("count")
+ && span.field("outcome") == Some("ok")),
+ "{login_iqs:#?}"
+ );
+ let passive: Vec<_> = iqs
+ .iter()
+ .filter(|span| span.field("xmlns") == Some("passive"))
+ .collect();
+ let failed = passive
+ .iter()
+ .find(|span| span.field("outcome") == Some("error"))
+ .expect("the failed query has a span");
+ assert_eq!(failed.field("error_code"), Some("500"));
+ assert_eq!(failed.field("otel.status_code"), Some("ERROR"));
+ assert_eq!(failed.field("iq_type"), Some("set"));
+ assert_eq!(failed.field("kind"), Some("passive"));
+ assert_eq!(failed.ancestors, ["account"]);
+ let timed_out = passive
+ .iter()
+ .find(|span| span.field("outcome") == Some("timeout"))
+ .expect("the timed out query has a span");
+ assert_eq!(timed_out.field("otel.status_code"), Some("ERROR"));
+
+ let values = spans
+ .iter()
+ .flat_map(|span| span.fields.iter())
+ .chain(captured.events.iter().flatten());
+ for (field, value) in values {
+ for jid_part in ["@s.whatsapp.net", "@lid", "1234:5", "9876:5"] {
+ assert!(
+ !value.contains(jid_part),
+ "field {field} holds a JID: {value}"
+ );
+ }
+ }
+}
diff --git a/crates/whatsmeow/src/upload.rs b/crates/whatsmeow/src/upload.rs
index 36258bdcc3..8decb5aa75 100644
--- a/crates/whatsmeow/src/upload.rs
+++ b/crates/whatsmeow/src/upload.rs
@@ -18,6 +18,7 @@ use base64::engine::general_purpose::{URL_SAFE, URL_SAFE_NO_PAD};
use hmac::{Hmac, Mac};
use serde::Deserialize;
use sha2::{Digest, Sha256};
+use tracing::Instrument;
use crate::download::{MEDIA_HMAC_LENGTH, MediaHttpClient, MediaType, get_media_keys};
use crate::mediaconn::MediaConn;
@@ -98,9 +99,18 @@ pub async fn upload(
app_info: MediaType,
) -> Result<UploadResponse, UploadError> {
let media_key: [u8; 32] = rand::random();
- let (mut resp, data_to_upload) = encrypt_media(plaintext, &media_key, app_info)?;
+ // Macro addition: encrypt and HTTP upload as child spans.
+ let (mut resp, data_to_upload) = tracing::info_span!("whatsmeow.media.encrypt")
+ .in_scope(|| encrypt_media(plaintext, &media_key, app_info))?;
let file_enc_sha256 = resp.file_enc_sha256.clone();
- raw_upload(
+ let upload_span = tracing::info_span!(
+ "whatsmeow.media.upload_http",
+ size = data_to_upload.len(),
+ outcome = tracing::field::Empty,
+ status_code = tracing::field::Empty,
+ otel.status_code = tracing::field::Empty,
+ );
+ let uploaded = raw_upload(
http,
media_conn,
data_to_upload,
@@ -109,7 +119,13 @@ pub async fn upload(
false,
&mut resp,
)
- .await?;
+ .instrument(upload_span.clone())
+ .await;
+ if let Err(UploadError::Status(status)) = &uploaded {
+ upload_span.record("status_code", status);
+ }
+ crate::telemetry::record_result(&upload_span, &uploaded);
+ uploaded?;
Ok(resp)
}
diff --git a/deny.toml b/deny.toml
index d901c36b79..617a359c98 100644
--- a/deny.toml
+++ b/deny.toml
@@ -251,6 +251,7 @@ deny = [
"tracing-tree",
"tracing-web", # External WASM tracing layer
"turso_core", # External Turso crate requires tracing-subscriber directly
+ "whatsmeow", # Span hierarchy and JID-redaction tests only
"worker-rs-otel", # Cloudflare/WASM OpenTelemetry integration
"workspace-hack", # cargo-hakari generated crate
], reason = "Use macro_entrypoint for tracing setup in workspace crates" },