Merge pull request #333 from ojung/ojung/feat/symdb-probe-signatures

Improve symdb probe-locations reliability and output

Author: ojung

docs/EXAMPLES.md

@@ -437,6 +437,13 @@ pup debugger probes create \
   --probe-location com.example.MyClass:myMethod \
   --capture "request.id" --capture "user.name"
 
+# Use a method signature from --view probe-locations output
+pup debugger probes create \
+  --service my-service \
+  --env staging \
+  --probe-location "com.example.MyClass:myMethod(String, int)" \
+  --capture "request.id"
+
 # Increase capture depth for nested objects (default: 1)
 pup debugger probes create \
   --service my-service \
@@ -507,6 +514,7 @@ pup debugger probes watch "probe-id" --wait 30
 ### Pipeline: Create and Watch
 ```bash
 # Search for a method, create a probe, and watch events
+# Note: --view probe-locations may output signatures like TYPE:METHOD(args)
 pup symdb search --service my-service --query MyController --view probe-locations \
   | head -1 \
   | xargs -I{} pup debugger probes create --service my-service --env staging --probe-location {} --capture --ttl 1h \
@@ -536,7 +544,7 @@ pup symdb search --service my-service --query MyController --view full
 # Scope names only
 pup symdb search --service my-service --query MyController --view names
 
-# Probe locations (type:method format)
+# Probe locations (type:method or type:method(args) format)
 pup symdb search --service my-service --query MyController --view probe-locations
 ```
 

skills/dd-debugger/SKILL.md

@@ -70,13 +70,13 @@ pup debugger probes delete <PROBE_ID>
 
 ## Service Context
 
-**Always run this before creating probes.** It returns JSON by default, showing environments with active instances, tracer versions, and supported probe features. If the service runs in multiple environments, ask the user which one to target — don't guess.
+**Always run this before creating probes.** It returns JSON by default (like all other commands) showing environments with active instances, tracer versions, and supported probe features. If the service runs in multiple environments, ask the user which one to target — don't guess.
 
 ```bash
-# Full JSON output (default, avoid)
+# Full JSON output (default)
 pup debugger context my-service
 
-# Compact: just the fields you need (preferably use this to avoid context bloat)
+# Compact: just the fields you need
 pup debugger context my-service --fields service,language,envs
 
 # Filter to a specific environment
@@ -117,13 +117,23 @@ pup debugger probes create \
   --capture "order.items[0].price"
 ```
 
+To disambiguate overloaded methods, pass a signature with argument types:
+
+```bash
+pup debugger probes create \
+  --service my-service \
+  --env staging \
+  --probe-location "com.example.MyClass:myMethod(int, java.lang.String)" \
+  --capture "user.name"
+```
+
 **Options:**
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--service` | Service name (required) | — |
 | `--env` | Environment (required) | — |
-| `--probe-location` | `TYPE:METHOD` (required) | — |
+| `--probe-location` | `TYPE:METHOD` or `TYPE:METHOD(args)` (required). The signature form disambiguates overloaded methods. | — |
 | `--language` | `java`, `python`, `dotnet`, `go` | Auto-detected from symdb |
 | `--capture EXPR` | Capture expression (repeatable). Use dot notation for fields, brackets for indexing. | None |
 | `--capture` | Without value: enable full snapshot (capture everything). | No snapshot |
@@ -300,7 +310,7 @@ pup debugger probes watch <ID> --limit 1 \
 | No events appearing | Check `--from` (default is `now`); probe may need time to instrument |
 | Instrumentation errors | Check stderr output from watch for status errors |
 | Auth error | Run `pup auth login` or set `DD_API_KEY` + `DD_APP_KEY` + `DD_SITE` |
-| Wrong method signature | Use the `dd-symdb` skill to find exact `TYPE:METHOD` values |
+| Wrong method signature | Use the `dd-symdb` skill to find exact `TYPE:METHOD` or `TYPE:METHOD(args)` values |
 
 ## References
 

skills/dd-pup/SKILL.md

@@ -27,7 +27,7 @@ Pup CLI for Datadog API operations. Supports OAuth2 and API key auth.
 | Check SLOs | `pup slos list` |
 | On-call teams | `pup on-call teams list` |
 | Security signals | `pup security signals list --query "*" --from 24h` |
-| Inspect runtime values | `pup debugger probes create --service my-svc --env prod --probe-location com.example.MyClass:myMethod` |
+| Inspect runtime values | `pup debugger probes create --service my-svc --env prod --probe-location "com.example.MyClass:myMethod"` or `"com.example.MyClass:myMethod(String, int)"` |
 | Find probe-able methods | `pup symdb search --service my-svc --query MyController --view probe-locations` |
 | Check auth | `pup auth status` |
 | Refresh token | `pup auth refresh` |
@@ -192,11 +192,17 @@ pup debugger context my-svc --env prod
 pup symdb search --service my-svc --query MyController --view probe-locations
 
 # Place a log probe with capture expressions
+# --probe-location accepts TYPE:METHOD or TYPE:METHOD(arg1, arg2, ...) with optional signature
 pup debugger probes create --service my-svc --env prod \
   --probe-location "com.example.MyController:handleRequest" \
   --capture "request.id" --capture "request.headers" \
   --ttl 1h
 
+# With method signature (useful when the method is overloaded)
+pup debugger probes create --service my-svc --env prod \
+  --probe-location "com.example.MyController:handleRequest(String, HttpHeaders)" \
+  --capture "request.id" --ttl 1h
+
 # Watch probe events — compact output
 pup debugger probes watch <PROBE_ID> --fields "message,captures,timestamp" --timeout 60 --limit 10 --wait 5
 

skills/dd-symdb/SKILL.md

@@ -46,7 +46,7 @@ pup symdb search --service my-service --query "Controller" --view names
 
 ### Probe Locations View
 
-`TYPE:METHOD` pairs suitable for `--probe-location` in `pup debugger probes create`.
+`TYPE:METHOD(arg1, arg2, ...)` signatures suitable for `--probe-location` in `pup debugger probes create`. Falls back to `TYPE:METHOD` when no argument info is available.
 
 ```bash
 pup symdb search --service my-service --query "VetController" --view probe-locations
@@ -81,6 +81,13 @@ pup debugger probes create \
   --probe-location "com.example.MyController:handleRequest" \
   --template "handleRequest called with id={id}"
 
+# Or use the full signature when multiple overloads exist
+pup debugger probes create \
+  --service my-service \
+  --env production \
+  --probe-location "com.example.MyController:handleRequest(int, java.lang.String)" \
+  --template "handleRequest called with id={id}"
+
 # 3. Stream events
 pup debugger probes watch <PROBE_ID> --timeout 60 --limit 10
 ```

src/client.rs

@@ -9,6 +9,26 @@ use reqwest_middleware::{Middleware, Next};
 
 use crate::config::Config;
 
+/// HTTP error with the status code preserved for programmatic matching.
+#[derive(Debug)]
+pub struct HttpError {
+    pub status: u16,
+    pub method: String,
+    pub url: String,
+    pub body: String,
+}
+
+impl std::fmt::Display for HttpError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{} {} failed (HTTP {}): {}",
+            self.method, self.url, self.status, self.body
+        )
+    }
+}
+
+impl std::error::Error for HttpError {}
 #[cfg(not(target_arch = "wasm32"))]
 struct BearerAuthMiddleware {
     token: String,
@@ -727,7 +747,7 @@ pub async fn raw_request(
     let client = reqwest::Client::new();
     let method_name = method.to_uppercase();
     let method = reqwest::Method::from_bytes(method_name.as_bytes())
-        .map_err(|_| anyhow::anyhow!("unsupported HTTP method: {method}"))?;
+        .map_err(|_| anyhow::anyhow!("unsupported HTTP method: {method_name}"))?;
     let mut req = client.request(method, &url);
     if !query.is_empty() {
         req = req.query(query);
@@ -754,7 +774,13 @@ pub async fn raw_request(
     if !resp.status().is_success() {
         let status = resp.status();
         let text = resp.text().await.unwrap_or_default();
-        anyhow::bail!("API error (HTTP {status}): {text}");
+        return Err(HttpError {
+            status: status.as_u16(),
+            method: method_name,
+            url,
+            body: text,
+        }
+        .into());
     }
 
     let resp_ct = resp
@@ -804,7 +830,13 @@ pub async fn raw_get(
     if !resp.status().is_success() {
         let status = resp.status();
         let body = resp.text().await.unwrap_or_default();
-        anyhow::bail!("GET {url} failed (HTTP {status}): {body}");
+        return Err(HttpError {
+            status: status.as_u16(),
+            method: "GET".into(),
+            url,
+            body,
+        }
+        .into());
     }
     Ok(resp.json().await?)
 }
@@ -833,7 +865,13 @@ pub async fn raw_patch(
     if !resp.status().is_success() {
         let status = resp.status();
         let body = resp.text().await.unwrap_or_default();
-        anyhow::bail!("PATCH {url} failed (HTTP {status}): {body}");
+        return Err(HttpError {
+            status: status.as_u16(),
+            method: "PATCH".into(),
+            url,
+            body,
+        }
+        .into());
     }
     Ok(resp.json().await?)
 }
@@ -882,7 +920,13 @@ async fn raw_post_impl(
     if !resp.status().is_success() {
         let status = resp.status();
         let body = resp.text().await.unwrap_or_default();
-        anyhow::bail!("POST {url} failed (HTTP {status}): {body}");
+        return Err(HttpError {
+            status: status.as_u16(),
+            method: "POST".into(),
+            url: url.to_string(),
+            body,
+        }
+        .into());
     }
     Ok(resp.json().await?)
 }
@@ -1008,7 +1052,13 @@ pub async fn raw_delete(cfg: &Config, path: &str) -> anyhow::Result<()> {
     if !resp.status().is_success() {
         let status = resp.status();
         let body = resp.text().await.unwrap_or_default();
-        anyhow::bail!("DELETE {url} failed (HTTP {status}): {body}");
+        return Err(HttpError {
+            status: status.as_u16(),
+            method: "DELETE".into(),
+            url,
+            body,
+        }
+        .into());
     }
     Ok(())
 }

src/commands/debugger.rs

@@ -91,6 +91,7 @@ struct ResolvedProbe<'a> {
     env: &'a str,
     type_name: &'a str,
     method_name: &'a str,
+    signature: Option<&'a str>,
     language: &'a str,
     template_str: String,
     segments: serde_json::Value,
@@ -207,13 +208,17 @@ fn build_probe_payload(p: &ResolvedProbe<'_>) -> serde_json::Value {
         "language": p.language,
         "where": {
             "type_name": p.type_name,
-            "method_name": p.method_name
+            "method_name": p.method_name,
         },
         "evaluate_at": "EXIT",
         "tags": [],
         "version": 0
     });
 
+    if let Some(sig) = p.signature {
+        probe["where"]["signature"] = serde_json::json!(sig);
+    }
+
     if let Some(w) = &p.when {
         probe["when"] = w.clone();
     }
@@ -286,10 +291,16 @@ pub async fn probes_create(cfg: &Config, params: ProbeCreateParams<'_>) -> Resul
         None
     };
 
-    let (type_name, method_name) = probe_location
+    let (type_name, method_part) = probe_location
         .rsplit_once(':')
         .ok_or_else(|| anyhow::anyhow!("probe_location must be in format TYPE:METHOD"))?;
 
+    // Split optional signature: "myMethod(int,int)" → method="myMethod", sig="(int,int)"
+    let (method_name, signature) = match method_part.find('(') {
+        Some(i) => (&method_part[..i], Some(&method_part[i..])),
+        None => (method_part, None),
+    };
+
     // Parse condition if provided
     let when = if let Some(cond) = condition {
         let body = serde_json::json!({
@@ -340,6 +351,7 @@ pub async fn probes_create(cfg: &Config, params: ProbeCreateParams<'_>) -> Resul
         env,
         type_name,
         method_name,
+        signature,
         language,
         template_str,
         segments,
@@ -730,6 +742,7 @@ mod tests {
             env: "staging",
             type_name: "com.example.MyClass",
             method_name: "myMethod",
+            signature: None,
             language: "java",
             template_str,
             segments,
@@ -996,6 +1009,61 @@ mod tests {
         assert!(out.get("bogus").is_none());
     }
 
+    #[test]
+    fn test_probe_location_parsing_plain() {
+        let loc = "com.example.MyClass:myMethod";
+        let (_, method_part) = loc.rsplit_once(':').unwrap();
+        let (method_name, signature) = match method_part.find('(') {
+            Some(i) => (&method_part[..i], Some(&method_part[i..])),
+            None => (method_part, None),
+        };
+        assert_eq!(method_name, "myMethod");
+        assert_eq!(signature, None);
+    }
+
+    #[test]
+    fn test_probe_location_parsing_with_signature() {
+        let loc = "com.example.MyClass:myMethod(int,java.lang.String)";
+        let (type_name, method_part) = loc.rsplit_once(':').unwrap();
+        let (method_name, signature) = match method_part.find('(') {
+            Some(i) => (&method_part[..i], Some(&method_part[i..])),
+            None => (method_part, None),
+        };
+        assert_eq!(type_name, "com.example.MyClass");
+        assert_eq!(method_name, "myMethod");
+        assert_eq!(signature, Some("(int,java.lang.String)"));
+    }
+
+    #[test]
+    fn test_probe_location_parsing_empty_args() {
+        let loc = "com.example.MyClass:myMethod()";
+        let (_, method_part) = loc.rsplit_once(':').unwrap();
+        let (method_name, signature) = match method_part.find('(') {
+            Some(i) => (&method_part[..i], Some(&method_part[i..])),
+            None => (method_part, None),
+        };
+        assert_eq!(method_name, "myMethod");
+        assert_eq!(signature, Some("()"));
+    }
+
+    #[test]
+    fn test_build_probe_payload_no_signature() {
+        let payload = test_resolved_probe(|_| {});
+        let where_block = &payload["data"]["attributes"]["probe"]["where"];
+        assert!(where_block.get("signature").is_none());
+    }
+
+    #[test]
+    fn test_build_probe_payload_with_signature() {
+        let payload = test_resolved_probe(|rp| {
+            rp.signature = Some("(int,java.lang.String)");
+        });
+        let where_block = &payload["data"]["attributes"]["probe"]["where"];
+        assert_eq!(where_block["type_name"], "com.example.MyClass");
+        assert_eq!(where_block["method_name"], "myMethod");
+        assert_eq!(where_block["signature"], "(int,java.lang.String)");
+    }
+
     fn sample_context_response() -> serde_json::Value {
         serde_json::json!({
             "data": {