job-workflow 0.1.3

data/guides/README.md

@@ -0,0 +1,174 @@
+# JobWorkflow Guides
+
+> ⚠️ **Early Stage (v0.1.3):** JobWorkflow is in active development. APIs and features may change. The following guides provide patterns and examples for building workflows, but be aware that implementations may need adjustment as the library evolves.
+
+Welcome to the JobWorkflow documentation! This directory contains comprehensive guides to help you build robust workflows with JobWorkflow.
+
+## 📚 Documentation Structure
+
+### 🚀 Getting Started
+
+Start here if you're new to JobWorkflow:
+
+- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Quick 5-minute introduction and detailed getting started guide
+  - What is JobWorkflow and why use it
+  - Installation and setup
+  - Your first workflow
+  - Core concepts (Workflow, Task, Arguments, Context, Outputs)
+
+### 📖 Fundamentals
+
+Core concepts and features you'll use in every workflow:
+
+- **[DSL_BASICS.md](DSL_BASICS.md)** - Mastering the JobWorkflow DSL
+  - Defining tasks
+  - Working with arguments
+  - Task dependencies
+  - Task options (retry, condition, throttle, timeout)
+
+- **[TASK_OUTPUTS.md](TASK_OUTPUTS.md)** - Understanding task outputs
+  - Defining and accessing outputs
+  - Using outputs with map tasks
+  - Output persistence and design patterns
+
+- **[PARALLEL_PROCESSING.md](PARALLEL_PROCESSING.md)** - Efficient parallel execution
+  - Collection task basics
+  - Fork-Join pattern
+  - Controlling concurrency
+  - Context isolation
+
+### 🔧 Intermediate
+
+Advanced workflow patterns and features:
+
+- **[ERROR_HANDLING.md](ERROR_HANDLING.md)** - Robust error handling
+  - Retry configuration (simple and advanced)
+  - Retry strategies (linear, exponential, jitter)
+  - Task-level and workflow-level retry settings
+  - Combining multiple retry layers
+
+- **[CONDITIONAL_EXECUTION.md](CONDITIONAL_EXECUTION.md)** - Dynamic workflow control
+  - Basic conditional execution
+  - Complex conditions
+  - Best practices
+
+- **[LIFECYCLE_HOOKS.md](LIFECYCLE_HOOKS.md)** - Extending task behavior
+  - Hook types (before, after, around, on_error)
+  - Hook scope (global vs task-specific)
+  - Execution order and error handling
+
+### 🎓 Advanced
+
+Power features for complex workflows:
+
+- **[DEPENDENCY_WAIT.md](DEPENDENCY_WAIT.md)** - Efficient dependency waiting
+  - The thread occupation problem
+  - Automatic job rescheduling
+  - Configuration options (poll_timeout, poll_interval, reschedule_delay)
+  - SolidQueue integration
+
+- **[NAMESPACES.md](NAMESPACES.md)** - Organizing large workflows
+  - Basic namespace usage
+  - Nested namespaces
+  - Cross-namespace dependencies
+
+- **[THROTTLING.md](THROTTLING.md)** - Rate limiting and resource control
+  - Task-level throttling
+  - Runtime throttling
+  - Sharing throttle keys across jobs
+
+- **[WORKFLOW_COMPOSITION.md](WORKFLOW_COMPOSITION.md)** - Composing and reusing workflows
+  - Invoking child workflows (sync/async)
+  - Accessing child workflow outputs
+  - Map tasks with child workflows
+  - Best practices and limitations
+
+- **[SCHEDULED_JOBS.md](SCHEDULED_JOBS.md)** - Cron-like job scheduling
+  - Schedule DSL basics
+  - Schedule expressions (cron and natural language)
+  - Multiple schedules per job
+  - SolidQueue integration
+
+### 📊 Observability
+
+Monitoring and debugging your workflows:
+
+- **[STRUCTURED_LOGGING.md](STRUCTURED_LOGGING.md)** - JSON-based logging
+  - Log event types
+  - Customizing the logger
+  - Querying and analyzing logs
+
+- **[INSTRUMENTATION.md](INSTRUMENTATION.md)** - Event-driven observability
+  - Architecture and event types
+  - Custom instrumentation
+  - Building custom subscribers
+
+- **[OPENTELEMETRY_INTEGRATION.md](OPENTELEMETRY_INTEGRATION.md)** - Distributed tracing
+  - Configuration and setup
+  - Span attributes and naming
+  - Viewing traces in your backend
+
+### 🏭 Practical
+
+Production deployment and operations:
+
+- **[PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md)** - Running JobWorkflow in production
+  - SolidQueue configuration
+  - Worker optimization
+  - Auto-scaling (AWS ECS)
+  - SolidCache configuration
+
+- **[QUEUE_MANAGEMENT.md](QUEUE_MANAGEMENT.md)** - Managing job queues
+  - Queue operations (status, pause, resume, clear)
+  - Finding workflows by queue
+  - Production best practices
+
+- **[CACHE_STORE_INTEGRATION.md](CACHE_STORE_INTEGRATION.md)** - Using cache store backends
+  - Automatic cache detection (SolidCache, MemoryStore)
+  - Cache operations and integration
+
+- **[WORKFLOW_STATUS_QUERY.md](WORKFLOW_STATUS_QUERY.md)** - Monitoring workflow execution
+  - Finding and inspecting workflows
+  - Accessing arguments, outputs, and job status
+  - Building dashboards and APIs
+
+- **[TESTING_STRATEGY.md](TESTING_STRATEGY.md)** - Testing your workflows
+  - Unit testing individual tasks
+  - Integration testing workflows
+  - Test best practices
+
+- **[DRY_RUN.md](DRY_RUN.md)** - Dry-run mode for safe testing
+  - Workflow-level and task-level dry-run
+  - Dynamic dry-run with Proc
+  - skip_in_dry_run for conditional execution
+  - Instrumentation and logging
+
+- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
+  - CircularDependencyError
+  - UnknownTaskError
+  - Debugging workflows
+
+### 📘 Reference
+
+Complete API documentation and best practices:
+
+- **[API_REFERENCE.md](API_REFERENCE.md)** - Detailed API documentation
+  - DSL method reference
+  - Class documentation
+  - Method signatures
+
+- **[BEST_PRACTICES.md](BEST_PRACTICES.md)** - Design patterns and recommendations
+  - Workflow design principles
+  - Task granularity
+  - Dependency management
+  - Testing strategies
+
+---
+
+## 🤝 Contributing
+
+Found an issue or have a suggestion? Please open an issue on the [GitHub repository](https://github.com/shoma07/job-workflow).
+
+## 📄 License
+
+JobWorkflow is released under the MIT License. See LICENSE file for details.

data/guides/SCHEDULED_JOBS.md

@@ -0,0 +1,165 @@
+# Scheduled Jobs
+
+JobWorkflow integrates with SolidQueue's recurring tasks feature to enable scheduled job execution. You can define schedules directly in your job class using the DSL, and JobWorkflow automatically registers them with SolidQueue.
+
+## Overview
+
+The `schedule` DSL method allows you to define cron-like schedules for your jobs. Multiple schedules can be defined for a single job, and all SolidQueue recurring task options are supported.
+
+### Key Features
+
+- **DSL-based configuration**: Define schedules inline with your job class
+- **SolidQueue integration**: Automatic registration with SolidQueue's recurring tasks
+- **Multiple schedules**: Support for multiple schedules per job
+- **All SolidQueue options**: key, args, queue, priority, description
+
+## Basic Usage
+
+```ruby
+class DailyReportJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  # Run daily at 9:00 AM
+  schedule "0 9 * * *"
+  
+  task :generate do |ctx|
+    ReportGenerator.generate_daily_report
+  end
+end
+```
+
+## Schedule Expression Formats
+
+JobWorkflow supports both cron expressions and natural language via the Fugit gem:
+
+```ruby
+# Cron expression
+schedule "0 9 * * *"        # Every day at 9:00 AM
+schedule "*/15 * * * *"     # Every 15 minutes
+schedule "0 0 1 * *"        # First day of every month at midnight
+
+# Natural language (Fugit)
+schedule "every hour"
+schedule "every 5 minutes"
+schedule "every day at 9am"
+```
+
+## Schedule Options
+
+The `schedule` method accepts several options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `key` | String/Symbol | Job class name | Unique identifier for the schedule |
+| `args` | Hash | `{}` | Arguments to pass to the job (as keyword arguments) |
+| `queue` | String/Symbol | nil | Queue name for the job |
+| `priority` | Integer | nil | Job priority |
+| `description` | String | nil | Human-readable description |
+
+### Using Options
+
+```ruby
+class DataSyncJob < ApplicationJob
+  include JobWorkflow::DSL
+
+  schedule "0 */4 * * *",
+           key: "data_sync_every_4_hours",
+           queue: "high_priority",
+           priority: 10,
+           args: { source: "primary" },
+           description: "Sync data from primary source every 4 hours"
+
+  argument :source, "String", default: "default"
+
+  task :sync do |ctx|
+    source = ctx.arguments.source
+    DataSynchronizer.sync(source)
+  end
+end
+```
+
+## Multiple Schedules
+
+You can define multiple schedules for the same job. When using multiple schedules, each must have a unique `key`:
+
+```ruby
+class ReportJob < ApplicationJob
+  include JobWorkflow::DSL
+
+  # Morning report
+  schedule "0 9 * * *", key: "morning_report"
+
+  # Evening report with different args
+  schedule "0 18 * * *",
+           key: "evening_report",
+           args: { time_of_day: "evening" }
+
+  argument :time_of_day, "String", default: "morning"
+
+  task :generate do |ctx|
+    time = ctx.arguments.time_of_day
+    ReportGenerator.generate(time)
+  end
+end
+```
+
+## How It Works
+
+JobWorkflow's schedule integration works through SolidQueue's configuration system:
+
+1. **Registration**: When a job class is loaded, schedules are stored in the `Workflow#schedules` hash
+2. **Tracking**: JobWorkflow tracks all loaded job classes via `JobWorkflow::DSL._included_classes`
+3. **Integration**: JobWorkflow patches `SolidQueue::Configuration#recurring_tasks_config` to merge registered schedules
+4. **Execution**: SolidQueue's scheduler picks up the schedules and enqueues jobs at the specified times
+
+### Configuration File Compatibility
+
+JobWorkflow schedules are merged with any existing SolidQueue YAML configuration:
+
+```yaml
+# config/recurring.yml (SolidQueue's native config)
+legacy_cleanup:
+  class: LegacyCleanupJob
+  schedule: "0 0 * * 0"
+```
+
+Both the YAML-defined schedules and JobWorkflow DSL-defined schedules will be active. If there's a key conflict, the JobWorkflow schedule takes precedence.
+
+## Requirements
+
+- SolidQueue must be configured as your ActiveJob backend
+- The job class must be loaded before SolidQueue's recurring task supervisor starts
+- Rails eager loading should be enabled in production (default behavior)
+
+## Checking Scheduled Jobs
+
+You can inspect registered schedules programmatically:
+
+```ruby
+# Get schedules from a specific job class
+DailyReportJob._workflow.build_schedules_hash
+# => {
+#   DailyReportJob: { class: "DailyReportJob", schedule: "0 9 * * *" }
+# }
+
+# For jobs with multiple schedules
+ReportJob._workflow.build_schedules_hash
+# => {
+#   morning_report: { class: "ReportJob", schedule: "0 9 * * *" },
+#   evening_report: { class: "ReportJob", schedule: "0 18 * * *", args: [{ time_of_day: "evening" }] }
+# }
+
+# Check if a workflow has schedules
+DailyReportJob._workflow.schedules.any?  # => true
+```
+
+## Best Practices
+
+1. **Use descriptive keys**: When defining multiple schedules, use meaningful keys that describe the schedule's purpose
+2. **Document schedules**: Use the `description` option to explain what each schedule does
+3. **Consider time zones**: Cron expressions use the server's time zone; consider using natural language for clarity
+4. **Test schedules**: Verify schedule expressions using Fugit before deployment:
+   ```ruby
+   require 'fugit'
+   Fugit.parse("0 9 * * *").next_time  # => next occurrence
+   ```

data/guides/STRUCTURED_LOGGING.md

@@ -0,0 +1,268 @@
+# Structured Logging
+
+JobWorkflow provides structured JSON logging for comprehensive workflow observability. All workflow and task lifecycle events are automatically logged with detailed context information.
+
+## Overview
+
+JobWorkflow's logging system uses a JSON formatter that outputs structured logs with timestamps, log levels, and event-specific fields. This makes it easy to search, filter, and analyze workflow execution in production environments.
+
+### Key Features
+
+- **JSON Format**: All logs are output in JSON format for easy parsing and analysis
+- **Automatic Logging**: Workflow and task lifecycle events are automatically logged
+- **Contextual Information**: Logs include job ID, task name, retry count, and other relevant metadata
+- **Customizable**: Logger instance and formatter can be customized
+- **Log Levels**: INFO for lifecycle events, WARN for retries, DEBUG for throttling
+
+## Log Event Types
+
+JobWorkflow automatically logs the following events:
+
+| Event | Description | Log Level | Fields |
+|-------|-------------|-----------|--------|
+| `workflow.start` | Workflow execution started | INFO | `job_name`, `job_id` |
+| `workflow.complete` | Workflow execution completed | INFO | `job_name`, `job_id` |
+| `task.start` | Task execution started | INFO | `job_name`, `job_id`, `task_name`, `each_index`, `retry_count` |
+| `task.complete` | Task execution completed | INFO | `job_name`, `job_id`, `task_name`, `each_index` |
+| `task.skip` | Task skipped (condition not met) | INFO | `job_name`, `job_id`, `task_name`, `reason` |
+| `task.enqueue` | Sub-jobs enqueued for map task | INFO | `job_name`, `job_id`, `task_name`, `sub_job_count` |
+| `task.retry` | Task retry after failure | WARN | `job_name`, `job_id`, `task_name`, `each_index`, `attempt`, `max_attempts`, `delay_seconds`, `error_class`, `error_message` |
+| `throttle.acquire.start` | Semaphore acquisition started | DEBUG | `concurrency_key`, `concurrency_limit` |
+| `throttle.acquire.complete` | Semaphore acquisition completed | DEBUG | `concurrency_key`, `concurrency_limit` |
+| `throttle.release` | Semaphore released | DEBUG | `concurrency_key` |
+| `dependent.wait.start` | Waiting for dependent task started | DEBUG | `job_name`, `job_id`, `dependent_task_name` |
+| `dependent.wait.complete` | Dependent task completed | DEBUG | `job_name`, `job_id`, `dependent_task_name` |
+
+## Default Configuration
+
+JobWorkflow automatically configures a logger with JSON output:
+
+```ruby
+# Default logger (outputs to STDOUT)
+JobWorkflow.logger
+# => #<ActiveSupport::Logger:...>
+
+JobWorkflow.logger.formatter
+# => #<JobWorkflow::Logger::JsonFormatter:...>
+```
+
+## Log Output Examples
+
+### Workflow Lifecycle
+
+```json
+{"time":"2026-01-02T10:00:00.123456+09:00","level":"INFO","progname":"ruby","event":"workflow.start","job_name":"DataProcessingJob","job_id":"abc123"}
+{"time":"2026-01-02T10:05:30.654321+09:00","level":"INFO","progname":"ruby","event":"workflow.complete","job_name":"DataProcessingJob","job_id":"abc123"}
+```
+
+### Task Execution
+
+```json
+{"time":"2026-01-02T10:00:01.234567+09:00","level":"INFO","progname":"ruby","event":"task.start","job_name":"DataProcessingJob","job_id":"abc123","task_name":"fetch_data","each_index":0,"retry_count":0}
+{"time":"2026-01-02T10:00:05.345678+09:00","level":"INFO","progname":"ruby","event":"task.complete","job_name":"DataProcessingJob","job_id":"abc123","task_name":"fetch_data","each_index":0}
+```
+
+### Task Retry
+
+```json
+{"time":"2026-01-02T10:00:10.456789+09:00","level":"WARN","progname":"ruby","event":"task.retry","job_name":"DataProcessingJob","job_id":"abc123","task_name":"process_item","each_index":5,"attempt":2,"max_attempts":3,"delay_seconds":4.0,"error_class":"Timeout::Error","error_message":"execution expired"}
+```
+
+### Task Skip (Conditional Execution)
+
+```json
+{"time":"2026-01-02T10:00:15.567890+09:00","level":"INFO","progname":"ruby","event":"task.skip","job_name":"DataProcessingJob","job_id":"abc123","task_name":"send_notification","reason":"condition_not_met"}
+```
+
+### Throttling Events
+
+```json
+{"time":"2026-01-02T10:00:20.678901+09:00","level":"DEBUG","progname":"ruby","event":"throttle.acquire.start","concurrency_key":"api_rate_limit","concurrency_limit":10}
+{"time":"2026-01-02T10:00:23.789012+09:00","level":"DEBUG","progname":"ruby","event":"throttle.acquire.complete","concurrency_key":"api_rate_limit","concurrency_limit":10}
+{"time":"2026-01-02T10:00:28.890123+09:00","level":"DEBUG","progname":"ruby","event":"throttle.release","concurrency_key":"api_rate_limit"}
+```
+
+## Customizing the Logger
+
+### Using a Custom Logger Instance
+
+You can replace the default logger with your own:
+
+```ruby
+# config/initializers/job_workflow.rb
+JobWorkflow.logger = ActiveSupport::Logger.new(Rails.root.join('log', 'job_workflow.log'))
+JobWorkflow.logger.formatter = JobWorkflow::Logger::JsonFormatter.new
+JobWorkflow.logger.level = :info
+```
+
+### Custom Log Tags
+
+Add custom tags to include in every log entry:
+
+```ruby
+# config/initializers/job_workflow.rb
+JobWorkflow.logger.formatter = JobWorkflow::Logger::JsonFormatter.new(
+  log_tags: [:request_id, :user_id]
+)
+
+# In your application code, set tags using ActiveSupport::TaggedLogging
+JobWorkflow.logger.tagged(request_id: request.request_id, user_id: current_user.id) do
+  MyWorkflowJob.perform_later
+end
+```
+
+Log output will include the tags:
+
+```json
+{"time":"2026-01-02T10:00:00.123456+09:00","level":"INFO","progname":"ruby","request_id":"req_xyz789","user_id":"user_123","event":"workflow.start","job_name":"MyWorkflowJob","job_id":"abc123"}
+```
+
+### Changing Log Level
+
+Control which logs are output by setting the log level:
+
+```ruby
+# config/environments/production.rb
+JobWorkflow.logger.level = :info  # INFO, WARN, ERROR only (no DEBUG)
+
+# config/environments/development.rb
+JobWorkflow.logger.level = :debug  # All logs including throttling details
+```
+
+## Querying and Analyzing Logs
+
+### Finding Failed Tasks
+
+```bash
+# Using jq
+cat log/production.log | jq 'select(.event == "task.retry")'
+
+# Using grep
+grep '"event":"task.retry"' log/production.log | jq .
+```
+
+### Tracking Workflow Execution
+
+```bash
+# Find all events for a specific job_id
+cat log/production.log | jq 'select(.job_id == "abc123")'
+
+# Calculate workflow duration
+START=$(cat log/production.log | jq -r 'select(.event == "workflow.start" and .job_id == "abc123") | .time' | head -1)
+END=$(cat log/production.log | jq -r 'select(.event == "workflow.complete" and .job_id == "abc123") | .time' | head -1)
+echo "Start: $START, End: $END"
+```
+
+### Analyzing Throttling Behavior
+
+```bash
+# Count throttle acquire events by concurrency_key
+cat log/production.log | jq -r 'select(.event == "throttle.acquire.start") | .concurrency_key' | sort | uniq -c
+
+# Calculate semaphore wait duration (requires timestamps)
+cat log/production.log | jq 'select(.event == "throttle.acquire.start" or .event == "throttle.acquire.complete")' | jq -s 'group_by(.concurrency_key) | map({key: .[0].concurrency_key, count: length})'
+```
+
+## Best Practices
+
+### 1. Use Appropriate Log Levels
+
+- **Production**: Set to `:info` to avoid verbose DEBUG logs
+- **Development**: Set to `:debug` to see all throttling and dependency events
+- **Staging**: Set to `:info` or `:debug` based on debugging needs
+
+### 2. Add Custom Tags for Context
+
+Use tagged logging to add request-specific context:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action :tag_job_workflow_logs
+
+  private
+
+  def tag_job_workflow_logs
+    JobWorkflow.logger.tagged(
+      request_id: request.request_id,
+      user_id: current_user&.id,
+      tenant_id: current_tenant&.id
+    ) do
+      yield
+    end
+  end
+end
+```
+
+### 3. Monitor Key Metrics
+
+Set up alerts for:
+
+- High retry rates: `event == "task.retry"`
+- Long workflow durations: time between `workflow.start` and `workflow.complete`
+- Long throttle wait times: duration between `throttle.acquire.start` and `throttle.acquire.complete`
+- Skipped tasks: unexpected `task.skip` events
+
+### 4. Structured Log Queries
+
+Design your monitoring queries around the JSON structure. Use `jq` for command-line analysis:
+
+```bash
+# Find all retry events for a specific job
+cat log/production.log | jq 'select(.event == "task.retry" and .job_name == "DataProcessingJob")'
+
+# Filter retries with 2 or more attempts
+cat log/production.log | jq 'select(.event == "task.retry" and .attempt >= 2)'
+
+# Extract specific fields
+cat log/production.log | jq 'select(.event == "task.retry") | {job_name, task_name, attempt, error_class}'
+```
+
+Most log aggregation services support JSON-based querying. Consult your logging platform's documentation for specific query syntax.
+
+### 5. Log Retention
+
+Configure appropriate retention policies based on your compliance and operational needs:
+
+- **High-volume production**: 7-30 days retention
+- **Critical workflows**: 90+ days retention
+- **Archive**: Store historical logs for compliance if required
+
+## Troubleshooting Logging Issues
+
+### Logs Not Appearing
+
+```ruby
+# Check logger configuration
+JobWorkflow.logger.level  # Should be :debug or :info
+JobWorkflow.logger.formatter.class  # Should be JobWorkflow::Logger::JsonFormatter
+
+# Verify logger is writing
+JobWorkflow.logger.info({ event: "test", message: "test message" })
+```
+
+### Malformed JSON
+
+If you see non-JSON log lines mixed with JSON:
+
+```ruby
+# Ensure all loggers use JsonFormatter
+Rails.logger.formatter = JobWorkflow::Logger::JsonFormatter.new  # If needed
+
+# Or separate JobWorkflow logs to a dedicated file
+JobWorkflow.logger = ActiveSupport::Logger.new('log/job_workflow.log')
+JobWorkflow.logger.formatter = JobWorkflow::Logger::JsonFormatter.new
+```
+
+### Missing Context Fields
+
+If expected fields are missing from logs:
+
+```ruby
+# Verify the logger has access to job context
+# The logger automatically includes job_name, job_id, task_name, etc.
+# Custom fields require tagged logging:
+
+JobWorkflow.logger.tagged(custom_field: "value") do
+  MyWorkflowJob.perform_later
+end
+```