Update documentation for Cloud Run v1.1.0 and add LOGSTORY_TIMESTAMP_DELTA support

[dandye]

Summary

Updates documentation and deployment configuration for v1.1.0 Cloud Run migration and adds LOGSTORY_TIMESTAMP_DELTA environment variable support.

Changes Made

Documentation Updates

• docs/index.md: Updated for v1.1.0 Cloud Run deployment
  • Changed "GCP Cloud Run functions" to "GCP Cloud Run Services"
  • Updated deployment instructions to use Makefile instead of Terraform
  • Added references to new Cloud Run Deployment Workflow guide
  • Removed obsolete Cloud Functions and Terraform instructions
  • Updated API requirements and service account setup

Cloud Run Deployment Improvements

• Makefile: Updated schedulers to use UTC timezone
  • Entities: 12:01 AM UTC (daily and every 3 days)
  • Events: 3:00 AM UTC (daily and every 3 days)
• Fixed Docker container args: Added "logstory" prefix to scheduler arguments
• Added LOGSTORY_TIMESTAMP_DELTA environment variable support:
  • New get_timestamp_delta_default() function reads from environment
  • Updated TimestampDeltaOption to use environment variable with "1d" default
  • Set LOGSTORY_TIMESTAMP_DELTA=1d on Cloud Run job deployment
  • Removed --timestamp-delta arguments from scheduler commands

Build Fixes

• .gitignore: Removed dist/* to allow wheel files in Cloud Build context

Benefits

• Simplified deployment: Uses environment variables instead of hardcoded scheduler arguments
• Better flexibility: Can override timestamp delta without recreating schedulers
• UTC scheduling: Consistent timing across regions
• Proper documentation: Reflects actual v1.1.0 Cloud Run architecture

Test Plan

• Build succeeds with new LOGSTORY_TIMESTAMP_DELTA support
• Makefile targets work with updated scheduler arguments
• Documentation accurately reflects Cloud Run deployment process

🤖 Generated with Claude Code

[dandye]

@claude please review

[claude]

Claude finished @dandye's task —— View job

---

Code Review for PR #36

I've completed my review of the Cloud Run v1.1.0 documentation updates and LOGSTORY_TIMESTAMP_DELTA environment variable support. Overall, this is a well-structured PR that successfully migrates from hardcoded scheduler arguments to environment variables. Here's my detailed feedback:

✅ Strengths

1. Environment Variable Implementation (src/logstory/logstory.py:142-144)

• Clean implementation of get_timestamp_delta_default() function
• Proper integration with Typer option system using function reference
• Good environment variable naming convention following LOGSTORY_ prefix
• Includes appropriate help text documentation

2. Makefile Scheduler Improvements

• UTC Standardization: Excellent move from America/New_York to UTC timezone for consistent deployment across regions
• Simplified Arguments: Removing hardcoded --timestamp-delta arguments in favor of environment variables is much cleaner
• Proper Container Args: Adding "logstory" prefix to container arguments ensures correct command execution
• Consistent Environment Setup: All Cloud Run deployments now set LOGSTORY_TIMESTAMP_DELTA=1d

3. Documentation Updates

• Terminology Correction: Changed "GCP Cloud Run functions" → "GCP Cloud Run Services" is accurate
• Simplified Instructions: Makefile-based deployment is indeed simpler than Terraform for this use case
• Architecture Clarity: Better explanation of single job with multiple schedulers approach

4. Build Configuration

• .gitignore Fix: Removing dist/* allows wheel files in Cloud Build context - essential for the deployment pipeline
• Version Bump: pyproject.toml version increment to 1.1.1 is appropriate for this feature addition

⚠️ Areas for Improvement

1. Documentation Inconsistency (docs/cloud-run-deployment-workflow.md:110-120)

# Documentation shows outdated schedule times:
1. **events-24h**: Daily at 8 AM  # Should be 3:00 AM UTC
2. **events-3day**: Every 3 days at 3 AM  # Correct
3. **entities-24h**: Daily at 9 AM  # Should be 12:01 AM UTC  
4. **entities-3day**: Every 3 days at 4 AM  # Should be 12:01 AM UTC

Recommendation: Update the documentation to reflect the actual scheduler times from the Makefile:

• events-*: Both at 3:00 AM UTC
• entities-*: Both at 12:01 AM UTC

2. Environment Variable Documentation
The PR description mentions removing --timestamp-delta arguments, but the documentation should clarify that:

• Default value is 1d (set via environment variable)
• Users can override this by changing the Cloud Run job's environment variables
• No need to recreate schedulers when changing the timestamp delta

3. Minor Code Style (src/logstory/logstory.py:242-243)
The help text could be more concise:

# Consider consolidating the help text formatting
"running logstory more than 1x per day. "
"(env: LOGSTORY_TIMESTAMP_DELTA)"

🔍 Technical Analysis

Environment Variable Handling: The implementation correctly:

• Uses os.getenv("LOGSTORY_TIMESTAMP_DELTA", "1d") for safe fallback
• Integrates with Typer's option system via function reference
• Maintains backward compatibility with CLI arguments

Scheduler Configuration: The changes properly:

• Standardize on UTC timezone for global deployment consistency
• Remove timestamp-related arguments from container overrides
• Set environment variables at the job level instead

Build System: The .gitignore change is necessary because:

• Cloud Build needs access to wheel files in the dist/ directory
• Previous dist/* ignore pattern would prevent wheel files from being included in build context

📊 Impact Assessment

Positive Impacts:

• ✅ Simplified deployment (no scheduler recreation needed for timestamp changes)
• ✅ Better flexibility for different environments
• ✅ Consistent UTC scheduling across all regions
• ✅ Proper Cloud Run service architecture documentation

Risk Assessment: LOW RISK

• Changes are backward compatible
• Environment variable has sensible default
• Existing deployments will continue working

🎯 Recommendations

1. Fix Documentation: Update docs/cloud-run-deployment-workflow.md lines 110-120 with correct scheduler times
2. Consider Enhancement: Document how users can change LOGSTORY_TIMESTAMP_DELTA after deployment without recreating schedulers
3. Optional: Add validation for LOGSTORY_TIMESTAMP_DELTA format in the get_timestamp_delta_default() function

✅ Approval

This PR successfully achieves its goals and represents a solid improvement to the logstory deployment system. The environment variable approach is more maintainable than hardcoded scheduler arguments, and the UTC standardization will prevent timezone-related issues.

Recommended Action: ✅ APPROVE after addressing the documentation inconsistency in the scheduler times.

---

Todo List:

• Read and analyze all 6 changed files
• Review code changes in src/logstory/logstory.py
• Check documentation updates for accuracy
• Review Makefile scheduler configuration changes
• Analyze .gitignore and pyproject.toml changes
• Provide comprehensive review feedback

---

[dandye]

@claude review comments addressed. Please re-review.

[claude]

Claude finished @dandye's task —— View job

---

Re-reviewing PR #36 ✅

I've completed a comprehensive re-review of all changes to verify if my previous review comments were addressed.

Todo List:

• Read all 6 changed files to understand current state
• Check if documentation scheduler times were corrected in cloud-run-deployment-workflow.md
• Verify other improvement areas from previous review
• Provide updated comprehensive review feedback

---

🎯 Review Comments Status: FULLY ADDRESSED ✅

✅ Primary Issue RESOLVED

Documentation Inconsistency Fixed (docs/cloud-run-deployment-workflow.md:110-121):

• ✅ events-24h: Daily at 3:00 AM UTC (matches Makefile "0 3 * * *")
• ✅ events-3day: Every 3 days at 3:00 AM UTC (matches Makefile "0 3 */3 * *")
• ✅ entities-24h: Daily at 12:01 AM UTC (matches Makefile "1 0 * * *")
• ✅ entities-3day: Every 3 days at 12:01 AM UTC (matches Makefile "1 0 */3 * *")

This was the main blocker from my previous review and it's now perfectly aligned!

✅ All Other Areas Maintained

1. Environment Variable Implementation (src/logstory/logstory.py:142-144):

   • ✅ get_timestamp_delta_default() function working properly
   • ✅ Integrates cleanly with Typer option system using function reference
   • ✅ Consistent LOGSTORY_ prefix naming convention

2. Makefile Configuration (Makefile:291, 306, 322):

   • ✅ All Cloud Run deployments set LOGSTORY_TIMESTAMP_DELTA=1d
   • ✅ UTC timezone standardization maintained ("UTC" in all schedulers)
   • ✅ Proper container arguments with "logstory" prefix

3. Documentation Quality (docs/index.md, docs/cloud-run-deployment-workflow.md):

   • ✅ Accurate terminology: "GCP Cloud Run Services"
   • ✅ Clear Makefile-based deployment instructions
   • ✅ Comprehensive environment variable documentation

4. Build System (.gitignore, pyproject.toml):

   • ✅ .gitignore properly allows wheel files for Cloud Build
   • ✅ Version bumped to 1.1.1 appropriately

---

🏆 Final Recommendation: APPROVED ✅

This PR successfully addresses all issues from my previous review. The implementation is clean, well-documented, and follows best practices:

Key Improvements Delivered:

• ✅ Fixed Documentation: Scheduler times now accurate across all docs
• ✅ Environment Variables: Clean implementation replaces hardcoded values
• ✅ UTC Standardization: Consistent timing across all regions
• ✅ Flexible Configuration: Easy to change LOGSTORY_TIMESTAMP_DELTA without recreating schedulers
• ✅ Simplified Deployment: Better maintainability and deployment experience

Quality Assessment:

• Architecture: ✅ Sound single-job with multiple schedulers approach
• Implementation: ✅ Clean code with proper environment variable integration
• Documentation: ✅ Accurate and comprehensive
• Compatibility: ✅ Backward compatible with existing deployments
• Testing: ✅ Changes are low-risk with sensible defaults

Impact:

• Risk Level: LOW - Environment variables have good defaults
• Deployment Impact: POSITIVE - Simplified configuration management
• User Experience: IMPROVED - More flexible and maintainable

---

This PR is ready for merge. All previous concerns have been addressed and the changes represent a solid improvement to the logstory Cloud Run deployment system.

---