sf-ai-agentforce-observability_skill

Overview

This skill extracts and analyzes Agentforce session tracing data from Salesforce Data 360 to support high-volume observability and debugging. It streamlines bulk extraction (1–10M records/day), writes efficient Parquet output, and provides Polars-based lazy analysis and session timeline reconstruction for fast troubleshooting. Use it to find routing issues, action failures, genAI quality signals, and performance bottlenecks in agent sessions.

How this skill works

The tool queries the Data 360 Query API for STDM DMOs (Session, Interaction, Step, Moment, GenAI audit tables), streams results into Parquet via PyArrow, and indexes by session/interaction IDs. Analysis uses Polars lazy frames to compute summaries, distributions, and topic routing across large datasets without loading everything into memory. A debug mode reconstructs per-session timelines, traces GenAI gateway links, and surfaces step-level errors and telemetry trace IDs for root-cause work.

When to use it

• Daily or incremental extracts when you need near real-time session observability at scale.
• Investigating failed steps, action errors, or unexpected agent behavior in specific sessions.
• Measuring agent performance: turn counts, durations, topic routing, and end-type distribution.
• Auditing GenAI trust signals (toxicity, PII, prompt defense, adherence) per generation.
• Integrating findings into remediation workflows for flows, Apex, or agent scripts.

Best practices

• Verify Data 360, Session Tracing, and JWT auth before running large extractions.
• Use incremental extraction for daily loads to avoid reprocessing millions of rows.
• Store outputs as partitioned Parquet and keep schema versions aligned with STDM updates.
• Prefer Polars lazy queries for aggregations and joins to minimize memory use.
• Correlate Moment rows to Sessions (agent name lives on Moment) when attributing agent activity.
• Capture telemetryTraceId/spanId from Interaction records for cross-system debugging.

Example use cases

• Run a 7-day extract and produce an agent-level summary of sessions, avg turns, and durations.
• Debug a single session by reconstructing the session tree, step inputs/outputs, and error messages.
• Detect and report GenAI PII or toxicity flags across recent generations and link back to sessions.
• Resume a failed extraction with extract-incremental to continue from the last checkpoint.
• Analyze topic routing failures by joining Interaction TopicApiName with Step outcomes.