Oro Api Logger Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • OroCommerce-Native: Designed specifically for OroCommerce’s REST API, leveraging its RestApiController decorator pattern, ensuring seamless integration with minimal architectural disruption.
  • Granular Logging Control: Supports configurable log levels (critical, error, info, debug) via a dedicated api_logger channel, enabling tailored observability without cluttering primary logs.
  • Non-Invasive Design: Uses dependency injection to wrap the existing controller, adhering to OroCommerce’s extension patterns and avoiding core logic modifications.
  • Structured Metadata: Logs include headers, bodies, timestamps, and status codes, providing comprehensive context for debugging and auditing.
  • Separation of Concerns: Isolates API logs to dedicated files (api-logger-[env].log), simplifying log management and reducing noise in application logs.

• Cons:

  • OroCommerce Dependency: Limited to OroCommerce ecosystems (v5.x/6.x), rendering it incompatible with other PHP/Symfony-based stacks or non-Oro APIs.
  • Synchronous Logging: Logs are written during request/response cycles, risking performance bottlenecks under high load or verbose logging (e.g., debug level).
  • No Built-in Retention: Log files require external management (e.g., logrotate, cloud storage), increasing operational overhead for long-term retention.
  • Lack of Structured Output: Logs are raw text, lacking schema or JSON formatting for advanced analytics or tooling (e.g., ELK, Datadog).

Integration Feasibility

• Low-Risk for OroCommerce:
  • Follows Oro’s decorator and configuration patterns, minimizing merge conflicts or core overrides.
  • Composer installation is straightforward, with no additional dependencies beyond Oro’s standard stack (Symfony Monolog).
• Dependencies:
  • OroCommerce 5.x/6.x: Explicitly tested; compatibility with older versions unvalidated.
  • Symfony Monolog: Standard in OroCommerce, ensuring seamless integration.
  • PHP 8.0+: Aligned with OroCommerce’s requirements, though no explicit version constraints are documented.

Technical Risk

• Critical Risks:

  • Performance Impact: Logging request/response bodies at debug level could degrade API performance, especially under high traffic. Mitigation: Default to info/error levels and monitor.
  • Sensitive Data Exposure: Logs may inadvertently capture PII (e.g., tokens, payment data) in request/response bodies. High risk if not addressed. Requires pre-integration review and potential sanitization (e.g., redaction of sensitive fields).
  • Log Volume: High-traffic APIs could generate excessive log data, necessitating storage solutions (e.g., centralized logging, log rotation).
  • Configuration Errors: Missing twenty5carat.api_logger.level parameter causes service container failures. Requires CI/CD validation or documentation enforcement.

• Moderate Risks:

  • Oro Upgrade Compatibility: Package supports Oro 6.x but lacks explicit testing for minor/patch updates. May require revalidation post-upgrade.
  • Custom API Routes: Assumes standard RestApiController usage; custom routes or middleware may need additional configuration.
  • Async Processing: No support for asynchronous logging, which could be critical for high-throughput APIs.

• Low Risks:

  • License: MIT license allows easy adoption and modification.
  • Codebase: Minimal and focused, with no external service dependencies.

Key Questions

1. Data Sensitivity and Compliance:
   • Are OroCommerce API endpoints logging PII or regulated data (e.g., PCI, GDPR)? If so, how will logs be sanitized (e.g., redaction, encryption) or secured (e.g., access controls, retention policies)?
2. Performance Baseline:
   • What is the expected API request volume? Will debug logging be feasible, or should it default to info/error to avoid performance degradation?
3. Observability Stack:
   • How will logs be aggregated and analyzed? (e.g., ELK, Datadog, custom scripts). Does the team require structured JSON logs for advanced tooling, or is raw text sufficient?
4. Retention and Storage:
   • Who will manage log file rotation/purging? Are there compliance-driven retention requirements (e.g., GDPR’s 6-year rule for financial data)?
5. Testing Coverage:
   • Has the package been validated with OroCommerce’s custom API routes (e.g., webhooks, GraphQL, or large payloads)? Are there edge cases (e.g., streaming responses) to address?
6. Rollback Plan:
   • How will logging be disabled or scaled back if performance issues arise? (e.g., feature flags, dynamic log level toggling).
7. Monitoring and Alerts:
   • Will logs trigger alerts for critical errors (e.g., 5xx responses)? If not, how will teams correlate logs with monitoring tools (e.g., Sentry, New Relic)?
8. Multi-Environment Configuration:
   • How will log levels differ across environments (e.g., debug in staging, error in production)? Will this be managed via configuration files or environment variables?

Integration Approach

Stack Fit

• Primary Use Cases:

  • API Debugging: Ideal for troubleshooting OroCommerce integrations (e.g., ERP, PIM, or third-party marketplace connections) by capturing raw request/response data.
  • Compliance/Auditing: Records client errors (4xx/5xx) and critical failures (e.g., payment processing errors) to meet regulatory requirements (e.g., GDPR, PCI-DSS).
  • Performance Analysis: Logs at info/debug levels enable analysis of latency bottlenecks (e.g., slow API responses, large payloads) without modifying core code.

• Stack Compatibility:

  • OroCommerce: Native support for Oro 5.x/6.x, with no conflicts with Oro’s default logging or API layers.
  • Symfony: Leverages Monolog, OroCommerce’s logging foundation, requiring no additional bundles.
  • PHP: Compatible with PHP 8.0+, aligning with OroCommerce’s requirements.
  • Infrastructure:
    • Local Logging: Defaults to file-based logs (api-logger-[env].log). For distributed systems, integrate with:
      • Centralized Logging: ELK, Splunk, or AWS CloudWatch via Monolog handlers.
      • SIEM Tools: Correlate API logs with security events (e.g., failed authentication attempts).
    • Async Processing: Not supported; consider queue-based logging (e.g., Laravel Horizon) for high-throughput APIs as a future enhancement.

Migration Path

1. Pre-Integration:

   • Audit Oro API Usage: Identify high-volume or sensitive endpoints to configure appropriate log levels and sanitization rules.
   • Backup Existing Logs: Archive current logs before enabling verbose logging to avoid data loss.
   • Test Environment Setup: Deploy the package in a staging environment to validate performance, log format, and compatibility with custom API routes.
   • Sanitization Plan: Document sensitive fields (e.g., tokens, payment data) that require redaction in logs.

2. Installation:

   • Add the package via Composer:

     composer require 25carat/oro-api-logger
     

   • Configure log level in parameters.yml.dist:

     parameters:
       twenty5carat.api_logger.level: info  # Start with info; adjust based on needs
     

   • Clear OroCommerce cache:

     php bin/console cache:clear
     

3. Post-Integration:

   • Validate Logs: Confirm logs appear in var/log/api-logger-[env].log and include expected data (headers, bodies, timestamps).
   • Performance Testing: Use tools like JMeter or Blackfire to measure API response times under load. Adjust log levels if bottlenecks are detected.
   • Sanitization Testing: Manually verify that sensitive data is not logged or is properly redacted.
   • Log Aggregation: If using centralized logging, configure Monolog handlers (e.g., ElasticsearchHandler, SyslogHandler) to forward logs.

Compatibility

• OroCommerce Versions:
  • Tested on 5.x/6.x. Oro 4.x compatibility is untested and may require backporting or alternative solutions.
• Custom API Routes:
  • Assumes standard RestApiController usage. Custom controllers or middleware may require additional configuration (e.g., decorating custom controllers).
• Logging Drivers:
  • Defaults to file logging. To use database or remote logging, extend Monolog handlers (e.g., Monolog\Handler\DatabaseHandler).
• Async Processing:
  • Not supported. For high-throughput APIs, consider implementing async logging via OroCommerce’s messaging system or a queue worker.

Sequencing

1. Phase 1: Development/Staging

   • Enable debug logging to capture full request/response details for comprehensive debugging.
   • Use logs to resolve integration issues, edge cases, or payload validation errors.
   • Iterate on sanitization rules to ensure no sensitive data leaks.

2. Phase 2: Pre-Production

   • Reduce log level to info or `error