EventLoomer

Appearance

EventLoomer Best Practices ​

Follow these guidelines to get the most value out of EventLoomer, whether you're using the direct HTTP API or an SDK.

Logging Strategy: Focus on Context ​

Well-contextualized logs are significantly more useful for debugging and analysis.

1. Use Appropriate Log Levels ​

Categorize logs correctly to filter noise and highlight important issues:

  • Trace/Debug: Verbose, low-level details for deep dives. Often disabled in production.
  • Information: Key operational events, start/end of processes, significant state changes. Your baseline for understanding flow.
  • Warning: Potential issues, recoverable errors, unexpected (but handled) conditions. Items to monitor.
  • Error: Failures that prevent an operation from completing successfully. Requires investigation.
  • Critical: Severe system-level failures impacting availability or core functionality. Requires immediate attention.

2. Send Structured Data ​

Whenever possible, send log data in a structured format (like JSON) within the payload (for External Logs) or scopeData/structured message properties (for Application Logs). This enables powerful filtering and searching within EventLoomer.

API Example (payload as JSON string):

json
{
    "uniqueIdentifier": "user-login-attempt",
    "payload": "{\"userId\": \"usr_123\", \"ipAddress\": \"192.168.1.100\", \"success\": false, \"reason\": \"InvalidPassword\"}",
    "level": "Warning",
    "correlationKey": "req-abc"
}

3. Track with Correlation Keys ​

For any operation that spans multiple steps, services, or asynchronous tasks, generate a unique correlationKey (e.g., a request ID, transaction ID) at the start and include it in all related log entries. This is essential for using the Event Flow view effectively.

4. Use Environments ​

Tag logs with the correct environment ("Production", "Staging", "QA", "Development", etc.). This is crucial for separating data and understanding issues specific to a deployment stage. Set a sensible default in your application and override if necessary when sending logs.

5. Log Key Business Events & Steps (External Logs) ​

Define meaningful Events and Steps in the EventLoomer UI that represent your core business processes (e.g., "UserRegistration", "OrderProcessing", "PaymentAttempted"). Log against these using the uniqueIdentifier field when sending External Logs. This provides high-level visibility in the Event Flow view.

6. Log Application Diagnostics (Application Logs) ​

Use Application Logs (associated with a ProjectId) for internal diagnostics, method entry/exit (at Trace/Debug level), detailed state information, and system-level events not directly part of a defined business Event/Step.

Performance Considerations ​

1. Batching (API & SDK) ​

For high-throughput applications, send logs in batches instead of individually.

  • API: Use the /api/ApplicationLogs/batch endpoint. Group logs logically before sending.
  • .NET SDK (ILogger): Batching is enabled by default and configurable (UseBatching, BatchSize, BatchTimeout). Defaults are usually sufficient.

2. Control Log Volume ​

  • Minimum Log Level: Configure your application (or the SDK's MinimumLogLevel) to avoid sending excessive Trace/Debug logs in production. Adjust dynamically if needed for troubleshooting.
  • Sampling (Advanced): For extremely high-volume informational logs, consider implementing client-side sampling if performance becomes an issue (not directly supported by the SDK currently).

3. Asynchronous Sending ​

Ensure log sending (especially via HTTP API) is done asynchronously and doesn't block your main application threads. The .NET SDK handles this automatically for ILogger.

Security Best Practices ​

1. API Key Security ​

  • Store your Team API Key securely using environment variables, configuration providers, or secret management tools. Do not embed API keys directly in source code.
  • Treat the API key like a password.
  • Use distinct Teams/API Keys for different environments (Dev, Staging, Prod) if strict access control is needed.

2. Avoid Logging Sensitive Data ​

  • Never log credentials, full PII (Personally Identifiable Information), API tokens, raw passwords, or full credit card numbers.
  • If logging related data is necessary (e.g., for tracing), log only non-sensitive identifiers (User ID, Order ID, last 4 digits of a card).
  • Consider data masking techniques within your application before logging if needed.
  • Use appropriate Log Levels – avoid logging potentially sensitive details at Information or higher in production. Keep sensitive debugging info at Debug or Trace.

Error Handling & Debugging ​

1. Log Exceptions Thoroughly ​

When logging errors, always include the exception details.

  • API: Include the exception message and stack trace in the exception field (Application Logs) or within the payload (External Logs).
  • .NET SDK (ILogger): Pass the Exception object directly to LogError/LogCritical.

2. Include Context ​

Make logs actionable by including relevant context: User IDs, Order IDs, Request IDs, relevant parameters, state information. Structured logging (JSON payloads or ILogger scopes/properties) is best for this.

3. Check API Responses ​

Remember that the EventLoomer ingestion APIs return HTTP 200 OK even on failure. Always check the success field in the JSON response body to confirm successful ingestion, especially when using the HTTP API directly. Implement retry logic if necessary for critical logs.

.NET SDK Specific Best Practices ​

1. Leverage ILogger and Scopes ​

  • Prefer using the standard ILogger integration for most application logging.
  • Use BeginScope effectively to add correlation IDs and other contextual data automatically to related logs.

2. Use EventId ​

  • Define static EventId instances for significant, recurring log messages to allow easier filtering and potential automated analysis.
csharp
public static class LoggingEvents
{
    public static readonly EventId UserLoginSuccess = new(1000, "UserLoginSuccess");
    public static readonly EventId UserLoginFailure = new(1001, "UserLoginFailure");
}

_logger.LogInformation(LoggingEvents.UserLoginSuccess, "User {UserId} logged in successfully.", userId);

3. Configure FailSilently ​

  • Set options.FailSilently = true in production to prevent SDK logging failures (network issues, etc.) from crashing your application.
  • Set options.FailSilently = false in development/testing to catch configuration or API issues early.
  • When FailSilently = true, check EventLoomerResponse.Success after IEventLoomerClient calls if you need confirmation of delivery.

4. Validate Configuration ​

  • Consider calling await client.ValidateConfigurationAsync() at startup (using injected IEventLoomerClient) to verify connectivity and API key validity before the application starts handling requests.