Manual Instrumentation
While Embrace's automatic instrumentation captures many important metrics and events out of the box, manual instrumentation allows you to add custom telemetry data that's specific to your application's unique workflows and business logic.
What is Manual Instrumentation?
Manual instrumentation refers to the explicit addition of code in your application to create traces, logs, handle errors, and monitor performance. This gives you the ability to:
- Track custom business processes
- Measure performance of critical operations
- Add context-specific attributes to telemetry data
- Capture application-specific events
- Create custom user journeys
Manual Instrumentation APIs
Embrace provides several APIs for manual instrumentation:
- Custom Traces - Measure the duration of custom operations with spans
- Custom Logging - Capture log messages at various severity levels
- Error Handling - Record and track errors that occur in your app
- Performance Monitoring - Track performance metrics for critical operations
- Crash Reporting - Configure crash reporting and integrate with Crashlytics
- Breadcrumbs - Add lightweight logging context to sessions
When to Use Manual Instrumentation
Consider adding manual instrumentation when:
- You need to track business-specific metrics not covered by automatic instrumentation
- You want to measure performance of critical algorithms or operations
- You need to track user journeys across multiple screens
- You want to add custom context to your telemetry data
- You need to capture application-specific events
- You want to track third-party SDK interactions
Basic Principles
Effective manual instrumentation follows these principles:
- Consistent naming - Use a consistent naming convention for spans and events
- Appropriate granularity - Create spans that are neither too broad nor too narrow
- Relevant attributes - Add attributes that provide useful context
- Error capturing - Record errors within the proper context
- Proper span hierarchy - Create logical parent-child relationships
Getting Started
The most common way to start with manual instrumentation is by creating custom spans:
// Create and start a span
let span = Embrace.client?.startSpan(name: "important_operation")
// Perform your operation
// ...
// Add some context to the span
span?.setAttribute(key: "operation_size", value: "large")
// Record success or failure
if success {
span?.end()
} else {
span?.recordError(error)
span?.setStatus(.error)
span?.end()
}
Explore the sections in this documentation to learn about all the available manual instrumentation capabilities.
Best Practices
- Start with automatic instrumentation and add manual instrumentation for business-critical paths
- Use descriptive names for spans and events that clearly indicate what they represent
- Add attributes that provide meaningful context for troubleshooting
- Create a standardized naming scheme for your organization
- Avoid creating too many spans which could impact performance
- Balance detail with volume to avoid overwhelming your telemetry data
Integration with Automatic Instrumentation
Manual instrumentation complements automatic instrumentation. For example:
- Add custom attributes to automatically captured spans
- Create custom spans as children of automatically captured spans
- Use custom events to mark significant points within automatically tracked user flows