feat(core): add child loggers for actor logging

[NathanFlurry]

No description provided.

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(core): add child loggers for actor logging #1216 👈 (View in Graphite)
• feat(core): add pino support #1215
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Child Loggers for Actor Logging

I've completed a thorough review of the PR that adds child loggers for actor logging functionality. Here's my comprehensive feedback:

Todo List

• Read and understand the changed files
• Analyze code quality and best practices
• Check for potential bugs or issues
• Review performance considerations
• Assess security concerns
• Evaluate test coverage needs
• Provide comprehensive feedback

---

Summary

This PR enhances the logging system by introducing child loggers for actors and actor runtime operations. The implementation provides structured logging with context-aware child loggers that include actor metadata like actor, key, and actorId.

Code Quality & Best Practices ✅

Strengths:

• Clean separation of concerns: Actor logs (#log) vs runtime logs (#rLog) are properly separated
• Consistent logger usage: Follows the CLAUDE.md guidelines by not storing loggers as variables but creating them on initialization
• Proper structured logging: Child loggers include relevant context (actor name, key, actorId)
• Comprehensive changes: All logging calls have been updated to use the appropriate child loggers

Areas for improvement:

• Consider documenting the difference between #log and #rLog in JSDoc comments in packages/rivetkit/src/actor/instance.ts:143-147

Potential Bugs & Issues 🟡

Minor concerns:

1. Logger initialization timing (packages/rivetkit/src/actor/instance.ts:288-296): The loggers are created during start() but the class has private fields that are marked with !. Consider initializing with placeholder loggers in the constructor to avoid potential undefined access.

2. Error handling in logger creation: No try-catch around getBaseLogger().child() calls. If logger creation fails, it could cause actor initialization to fail unexpectedly.

3. Memory considerations: Child loggers create new logger instances for each actor. For systems with many actors, consider the memory overhead.

Performance Considerations ✅

Good practices:

• Child loggers are created once during actor initialization rather than on each log call
• Proper reuse of logger instances throughout the actor lifecycle
• No performance impact on existing logging patterns

Recommendations:

• The implementation is performance-conscious and shouldn't introduce significant overhead

Security Concerns ✅

Analysis:

• No sensitive data exposure in log context
• Proper handling of actor metadata in log structured data
• No injection vulnerabilities introduced
• Log levels and targeting preserved from base configuration

Architecture & Design ✅

Strong points:

• Consistent with project patterns: Uses the same child logger pattern as seen in other parts of the codebase
• Proper encapsulation: Private fields with appropriate access patterns
• Clear responsibility separation: Actor logs vs runtime logs serve different purposes
• Integration with existing systems: Seamlessly integrates with the pino-based logging infrastructure

Missing Test Coverage ⚠️

Recommendations:

• Add unit tests to verify child loggers are created with correct context
• Test that actor and runtime logs use different logger instances
• Verify log context includes expected fields (actor, key, actorId, target)
• Test logger behavior during actor lifecycle (start, stop, error scenarios)

Specific Code Feedback

packages/rivetkit/src/actor/instance.ts:288-296

this.#log = getBaseLogger().child(
    Object.assign(getIncludeTarget() ? { target: "actor" } : {}, logParams),
);
this.#rLog = getBaseLogger().child(
    Object.assign(
        getIncludeTarget() ? { target: "actor-runtime" } : {},
        logParams,
    ),
);

Excellent: Clean separation between user-facing actor logs and internal runtime logs with appropriate targeting.

packages/rivetkit/src/actor/log.ts:3-6

/** Prefer to use ActorInstance.rlog child logger. This does not provide context in the log, should only be used as a last resort if you cannot pass the actor's child logger. */
export function loggerWithoutContext() {
    return getLogger("actor-runtime");
}

Good: Clear documentation about when to use the context-less logger vs child loggers.

Logging patterns throughout codebase

Consistent: All logger() calls have been properly replaced with actor.rLog or appropriate child logger usage.

Overall Assessment

This is a well-implemented enhancement that improves observability without introducing significant risks. The code follows established patterns and provides clear separation between different types of logging.

Recommendation: ✅ APPROVE

Minor Suggestions:

1. Add JSDoc comments explaining the difference between #log and #rLog
2. Consider adding unit tests for logger initialization and context
3. Document the child logger pattern in relevant README or documentation

The implementation is production-ready and aligns well with the project's logging architecture and guidelines.

---

[pkg-pr-new]

More templates

• example-ai-agent
• example-better-auth-external-db
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• counter
• example-crdt
• example-database
• example-sqlite
• example-elysia
• example-express
• example-game
• example-hono
• example-hono-react
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/actor@1216

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/cloudflare-workers@1216

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/core@1216

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/db@1216

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/framework-base@1216

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/next-js@1216

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/react@1216

rivetkit

pnpm add https://pkg.pr.new/rivet-gg/rivetkit@1216

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/sql-loader@1216

commit: 1bc911b

[graphite-app]

Merge activity

• Sep 13, 10:24 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Sep 13, 10:25 PM UTC: CI is running for this pull request on a draft pull request (#1217) due to your merge queue CI optimization settings.
• Sep 13, 10:26 PM UTC: Merged by the Graphite merge queue via draft PR: #1217.

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Child Loggers for Actor Logging

Summary

This PR introduces child loggers for actors, enhancing the logging system with context-aware structured logging. The implementation adds two types of child loggers:

• #log - Actor logs intended for user-facing actor logging
• #rLog - Runtime logs intended for internal actor operations

---

✅ Code Quality & Best Practices

Strengths:

• Clean separation of concerns: Actor logs (#log) vs runtime logs (#rLog) serve distinct purposes
• Consistent with project guidelines: Follows CLAUDE.md logging patterns - creates loggers once during initialization rather than storing as variables
• Proper structured logging: Child loggers include relevant context (actor, key, actorId, target)
• Comprehensive migration: All existing logger() calls updated to use appropriate child loggers

Minor suggestions:

• Consider adding JSDoc comments to explain the difference between #log and #rLog in packages/rivetkit/src/actor/instance.ts:143-147

---

🟡 Potential Issues & Bugs

Logger initialization timing (packages/rivetkit/src/actor/instance.ts:288-296):

• Private fields #log! and #rLog! marked with ! but initialized in start() method
• Consider initializing with placeholder loggers or ensuring initialization happens before any potential access

Memory considerations:

• Child loggers create new instances for each actor - acceptable overhead for the observability benefits
• No memory leaks detected in the implementation

Error handling:

• No try-catch around getBaseLogger().child() calls - if logger creation fails, could cause actor initialization failures

---

✅ Performance Considerations

Well-optimized:

• Child loggers created once during actor initialization, not on each log call
• Proper reuse of logger instances throughout actor lifecycle
• No performance regression on existing logging patterns
• Efficient context assignment using Object.assign()

---

✅ Security Assessment

No security concerns identified:

• Actor metadata in log context is safe to expose
• No sensitive data leakage through log structured fields
• Proper isolation between different log targets (actor vs actor-runtime)

---

⚠️ Test Coverage

Missing test coverage for:

• Child logger initialization with correct context
• Verification that #log and #rLog use different logger instances
• Log context includes expected fields (actor, key, actorId, target)
• Logger behavior during actor lifecycle events

Recommendation: Add unit tests for logger functionality

---

📝 Specific Code Feedback

packages/rivetkit/src/actor/instance.ts:288-296

this.#log = getBaseLogger().child(
    Object.assign(getIncludeTarget() ? { target: "actor" } : {}, logParams),
);
this.#rLog = getBaseLogger().child(
    Object.assign(
        getIncludeTarget() ? { target: "actor-runtime" } : {},
        logParams,
    ),
);

✅ Excellent: Clean separation with appropriate targeting for different log types.

packages/rivetkit/src/actor/log.ts:3-6

/** Prever to use ActorInstance.rlog child logger. This does not provide context in the log, should only be used as a last resort if you cannot pass the actor's child logger. */

Minor typo: "Prever" should be "Prefer"

Logger usage patterns throughout codebase

✅ Consistent: All logger() calls properly replaced with actor.rLog or appropriate child logger usage.

---

🎯 Architecture & Design

Strong architectural decisions:

• Consistent with existing patterns: Uses same child logger approach as other parts of the codebase
• Proper encapsulation: Private fields with appropriate access patterns
• Clear responsibility separation: Actor vs runtime logs serve different purposes
• Seamless integration: Works well with existing pino-based logging infrastructure

---

📊 Overall Assessment

✅ APPROVE - This is a well-implemented enhancement that significantly improves observability without introducing risks.

Key benefits:

1. Enhanced debugging: Context-aware logs make troubleshooting much easier
2. Structured logging: Consistent metadata across all actor operations
3. Clean separation: User-facing vs internal logs properly differentiated
4. Production ready: No performance or security concerns

Minor improvements needed:

1. Fix typo in packages/rivetkit/src/actor/log.ts:3
2. Add unit tests for logger functionality
3. Consider JSDoc documentation for logger field differences

This PR follows established patterns, maintains code quality standards, and provides valuable observability improvements to the RivetKit actor system.

---

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Child Loggers for Actor Logging

I've completed a comprehensive review focusing on code quality, potential bugs, performance, security, and test coverage.

Todo List

• Read and understand the changed files
• Analyze code quality and best practices
• Check for potential bugs or issues
• Review performance considerations
• Assess security concerns
• Evaluate test coverage needs
• Provide comprehensive feedback

---

Summary

This PR enhances the logging system by introducing child loggers for actors and actor runtime operations. The implementation provides structured logging with context-aware child loggers that include actor metadata like actor, key, and actorId.

Code Quality & Best Practices ✅

Strengths:

• Clean separation of concerns: Actor logs (#log) vs runtime logs (#rLog) are properly separated in packages/rivetkit/src/actor/instance.ts:143-147
• Consistent logger usage: Follows the CLAUDE.md guidelines by not storing loggers as variables but creating them on initialization
• Proper structured logging: Child loggers include relevant context (actor name, key, actorId)
• Comprehensive changes: All logging calls have been updated to use the appropriate child loggers throughout the codebase

Areas for improvement:

• Consider documenting the difference between #log and #rLog in JSDoc comments
• The typo in packages/rivetkit/src/actor/log.ts:3 - "Prever" should be "Prefer"

Potential Bugs & Issues 🟡

Minor concerns:

1. Logger initialization timing (packages/rivetkit/src/actor/instance.ts:288-296): The loggers are created during start() but the class has private fields marked with !. Consider initializing with placeholder loggers in the constructor to avoid potential undefined access before start() is called.

2. Error handling in logger creation: No try-catch around getBaseLogger().child() calls. If logger creation fails, it could cause actor initialization to fail unexpectedly.

3. Memory considerations: Child loggers create new logger instances for each actor. For systems with many actors, consider the memory overhead, though this is likely acceptable for most use cases.

Performance Considerations ✅

Good practices:

• Child loggers are created once during actor initialization rather than on each log call
• Proper reuse of logger instances throughout the actor lifecycle
• No performance impact on existing logging patterns

Recommendations:

• The implementation is performance-conscious and shouldn't introduce significant overhead

Security Concerns ✅

Analysis:

• No sensitive data exposure in log context
• Proper handling of actor metadata in log structured data
• No injection vulnerabilities introduced
• Log levels and targeting preserved from base configuration

Architecture & Design ✅

Strong points:

• Consistent with project patterns: Uses the same child logger pattern as seen in other parts of the codebase
• Proper encapsulation: Private fields with appropriate access patterns (#log, #rLog)
• Clear responsibility separation: Actor logs vs runtime logs serve different purposes
• Integration with existing systems: Seamlessly integrates with the pino-based logging infrastructure

Missing Test Coverage ⚠️

Recommendations:

• Add unit tests to verify child loggers are created with correct context
• Test that actor and runtime logs use different logger instances
• Verify log context includes expected fields (actor, key, actorId, target)
• Test logger behavior during actor lifecycle (start, stop, error scenarios)

Specific Code Feedback

packages/rivetkit/src/actor/instance.ts:288-296

this.#log = getBaseLogger().child(
    Object.assign(getIncludeTarget() ? { target: "actor" } : {}, logParams),
);
this.#rLog = getBaseLogger().child(
    Object.assign(
        getIncludeTarget() ? { target: "actor-runtime" } : {},
        logParams,
    ),
);

Excellent: Clean separation between user-facing actor logs and internal runtime logs with appropriate targeting.

packages/rivetkit/src/actor/log.ts:3-6

/** Prever to use ActorInstance.rlog child logger. This does not provide context in the log, should only be used as a last resort if you cannot pass the actor's child logger. */
export function loggerWithoutContext() {
    return getLogger("actor-runtime");
}

Good: Clear documentation about when to use the context-less logger vs child loggers. Note: "Prever" should be "Prefer".

Logging patterns throughout codebase

Consistent: All logger() calls have been properly replaced with actor.rLog or appropriate child logger usage, maintaining consistency across:

• Connection handling (packages/rivetkit/src/actor/connection.ts)
• Generic connection drivers (packages/rivetkit/src/actor/generic-conn-driver.ts)
• Router endpoints (packages/rivetkit/src/actor/router-endpoints.ts)

Overall Assessment

This is a well-implemented enhancement that improves observability without introducing significant risks. The code follows established patterns and provides clear separation between different types of logging.

Recommendation: ✅ APPROVE

Minor Suggestions:

1. Add JSDoc comments explaining the difference between #log and #rLog
2. Fix typo: "Prever" → "Prefer" in packages/rivetkit/src/actor/log.ts:3
3. Consider adding unit tests for logger initialization and context
4. Document the child logger pattern in relevant README or documentation

The implementation is production-ready and aligns well with the project's logging architecture and guidelines.

---