AgentSkillsCN

fullstory-logging

Fullstory日志API的核心概念。涵盖日志级别、消息格式化、隐私考量及最佳实践的跨平台指南。请参阅SKILL-WEB.md和SKILL-MOBILE.md获取实施示例。

SKILL.md
--- frontmatter
name: fullstory-logging
version: v3
description: Core concepts for Fullstory's Logging API. Platform-agnostic guide covering log levels, message formatting, privacy considerations, and best practices. See SKILL-WEB.md and SKILL-MOBILE.md for implementation examples.
platforms:
  - web
  - ios
  - android
  - flutter
  - react-native
implementation_files:
  - SKILL-WEB.md
  - SKILL-MOBILE.md
related_skills:
  - fullstory-observe-callbacks
  - fullstory-analytics-events
  - fullstory-async-methods

Fullstory Logging API

Implementation Files: This document covers core concepts. For code examples, see:

Overview

Fullstory's Logging API allows developers to send log messages directly to Fullstory sessions. These logs appear in the session replay, providing valuable context for debugging user issues, tracking application state, and understanding user workflows—without cluttering the device's console or logging systems.

Key use cases:

  • •Error Context: Log errors with stack traces viewable in replay
  • •Application State: Record important state changes
  • •Debugging: Add contextual information during development
  • •Audit Trail: Log significant user actions
  • •Support Context: Add logs that support teams can see in sessions

Core Concepts

Log Levels

All platforms support the same log levels, though the syntax differs:

LevelUse ForSeverity
logGeneral informationLowest
infoInformational messagesLow
warnWarning conditionsMedium
errorError conditionsHigh
debugDebug informationVaries

Key Behaviors

BehaviorDescription
Session-onlyLogs appear in Fullstory session replay, not device console
Session contextLogs viewable in session replay timeline
TimestampedAutomatically timestamped by Fullstory
SearchableCan search sessions by log content
String messagesAll platforms require string messages

When to Use FS Logging vs Device Console

Use FS LoggingUse Device Console
Production errors you want in replayDevelopment-only debugging
State changes for support contextVerbose tracing during development
User action audit trailsPerformance timing logs
Integration errorsInternal debugging
Customer-facing error contextCI/CD diagnostics

Data Privacy

Never log sensitive data:

  • •❌ Passwords, API keys, tokens
  • •❌ Credit card numbers, CVVs
  • •❌ Social Security numbers
  • •❌ Personal health information
  • •❌ Full email addresses (use user IDs instead)

Safe to log:

  • •✅ User IDs (non-PII identifiers)
  • •✅ Action names and types
  • •✅ Error messages and codes
  • •✅ Application state indicators
  • •✅ Timing and performance metrics

Best Practices

1. Use Appropriate Log Levels

code
debug   → Development troubleshooting, verbose details
log     → General operational information
info    → Significant but normal events
warn    → Potential issues, degraded functionality
error   → Failures requiring attention

2. Structure Log Messages Consistently

  • •Include context: action name, identifiers, state
  • •Use consistent prefixes for categorization: [Auth], [Payment], [API]
  • •Include relevant IDs for correlation
  • •Keep messages concise but informative

3. Log Strategically

Good to log:

  • •API failures and errors
  • •Authentication events (login/logout)
  • •Critical user actions (checkout, form submit)
  • •State transitions
  • •Third-party integration events

Avoid logging:

  • •Every mouse movement or scroll
  • •High-frequency events in loops
  • •Sensitive/PII data
  • •Redundant information

4. Create Centralized Logging Utilities

Build wrapper functions that:

  • •Add consistent formatting
  • •Include timestamps and context
  • •Check for Fullstory availability
  • •Sanitize potentially sensitive data

Rate Limits and Constraints

ConstraintLimit
Message typeString only (no objects)
Rate limitingStandard API rate limits apply
Excessive loggingMay be throttled
Message lengthKeep concise; very long messages may be truncated

Common Patterns

Error Logging Pattern

  1. •Capture error details (message, type, stack)
  2. •Add context (action, state, identifiers)
  3. •Format as readable string
  4. •Send to Fullstory with error level
  5. •Optionally send to other error tracking services

Audit Trail Pattern

  1. •Define standard action format
  2. •Include timestamp, action name, details
  3. •Use info level for normal operations
  4. •Use warn for unusual but valid actions
  5. •Use error for failed operations

Integration Logging Pattern

  1. •Log connection attempts
  2. •Log successful connections
  3. •Log disconnections with reasons
  4. •Log errors with operation context
  5. •Log timeouts with duration

Key Takeaways for Agent

When helping developers implement Fullstory logging:

  1. •

    Always emphasize:

    • •Message format: Always pass strings, not objects or arrays
    • •Privacy: Never log PII, passwords, or sensitive data
    • •Log levels: Use appropriate severity levels
    • •Frequency: Log significant events, not every operation
  2. •

    Common mistakes to watch for:

    • •Logging objects instead of strings
    • •Including PII in log messages
    • •Excessive logging causing noise
    • •Using wrong log levels
  3. •

    Platform routing:

    • •Web (JavaScript/TypeScript) → See SKILL-WEB.md
    • •iOS (Swift) → See SKILL-MOBILE.md § iOS
    • •Android (Kotlin) → See SKILL-MOBILE.md § Android
    • •Flutter (Dart) → See SKILL-MOBILE.md § Flutter
    • •React Native → See SKILL-MOBILE.md § React Native

Reference Links