Introducing implicit contexts in LogTape .0

I'm excited to announce the release of LogTape 0.7.0, which introduces implicit contexts—a powerful new feature that makes it easier than ever to add contextual information to your logs across your entire application.

What are implicit contexts?

Imagine you're handling an HTTP request in your application. You want every log message generated during the request processing to include the request ID, regardless of where in your codebase the log is created. Before implicit contexts, you would need to:

1. Pass the request ID through every function call
2. Create a new logger with context for each module
3. Or use global variables (which have their own problems)

With implicit contexts, you can now set context at the beginning of your request handler, and every log message within that execution context will automatically include that information. Here's a simple example:

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

How does it work?

Implicit contexts use the underlying runtime's context-local storage mechanisms (like Node.js's AsyncLocalStorage) to maintain contextual information throughout the execution of your code. This means the context is properly maintained even across asynchronous operations.

To enable implicit contexts in your application, you need to configure LogTape with a context-local storage:

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

Nested contexts and priority

One of the powerful features of implicit contexts is that they can be nested. When you nest contexts, the inner context inherits and can override values from the outer context:

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

When it comes to resolving context values, LogTape follows a clear priority order:

1. Explicit properties in the log message take highest priority
2. Explicit context set via Logger.with() takes second priority
3. Implicit context set via withContext() takes lowest priority

Runtime support

As of October 2024, implicit contexts are supported in:

• Node.js
• Deno
• Bun

Web browsers don't yet support implicit contexts, as they await the implementation of the TC39 Async Context proposal.

Use cases

Implicit contexts are particularly valuable for:

1. Request Tracing: Add request IDs, user IDs, or session IDs to all logs within a request
2. Transaction Monitoring: Track transaction IDs across multiple operations
3. Error Context: Ensure error logs always have relevant contextual information
4. Performance Monitoring: Add timing information across multiple operations
5. Tenant Context: In multi-tenant applications, track tenant information across all operations

Best practices

When using implicit contexts, consider these best practices:

1. Use implicit contexts for information that truly belongs to the entire execution context
2. Keep context data lightweight—remember it's carried through the entire execution
3. Use meaningful, consistent key names across your application
4. Consider using TypeScript to ensure context structure consistency
5. Document the expected context structure for your application

Migration Guide

If you're already using LogTape, upgrading to use implicit contexts is straightforward:

1. Update to LogTape 0.7.0
2. Add context-local storage to your LogTape configuration
3. Identify places where context is being manually passed around
4. Replace with withContext() calls at appropriate boundaries

Conclusion

Implicit contexts in LogTape 0.7.0 provide a powerful way to add contextual information to your logs without cluttering your code or manually passing context through your call stack. They're especially valuable in web services, APIs, and other applications where tracking context across operations is important.

I'm excited to see how you'll use this feature to improve your application's logging and observability. Give it a try and let me know what you think!

For more information, check out the complete documentation on implicit contexts.

The above is the detailed content of Introducing implicit contexts in LogTape .0. For more information, please follow other related articles on the PHP Chinese website!