Download the PHP package gemvc/apm-tracekit without Composer

GEMVC APM TraceKit Provider

TraceKit APM provider implementation for GEMVC framework. This package implements the GEMVC APM Contracts interface, providing distributed tracing and performance monitoring for GEMVC applications.

⬇️ Installation

TraceKit is automatically included when you install gemvc/library - no separate installation required!

If you're using GEMVC framework, TraceKit APM is already available and ready to configure. Simply run the setup wizard:

Note: If you need to install this package standalone (outside of GEMVC framework), you can still use:

This package automatically installs gemvc/apm-contracts as a dependency, which provides the base interfaces and abstract classes.

🎯 Architecture

This package is built on top of the GEMVC APM Contracts package:

Key Components:

• TraceKitProvider - Main APM provider class extending AbstractApm (used by ApmFactory)
• TraceKitModel - Alternative APM provider implementation extending AbstractApm (with additional methods like addEvent())
• TraceKitToolkit - Client-side integration and management class extending AbstractApmToolkit
• OpenTelemetry OTLP JSON Format - Sends traces in standard OpenTelemetry format
• Batch Trace Sending - Uses AbstractApm's batching system with synchronous ApiCall for reliable trace delivery (compatible with OpenSwoole production)

🔐 Configuration

Environment Variables

Set in your .env file:

Note: The TraceKit endpoint URL (https://app.tracekit.dev/v1/traces) is pre-configured as a library constant and does not need to be set in your .env file. If you need to override it (e.g., for custom deployments), you can set TRACEKIT_ENDPOINT in your .env file.

Configuration Priority

Configuration values are loaded in the following priority order:

1. Config array (passed to constructor/init) - Highest priority
2. Provider-specific env vars (TRACEKIT_*) - Medium priority
3. Unified APM env vars (APM_*) - Lower priority
4. Default values - Lowest priority

Unified API Key Support

You can use either TRACEKIT_API_KEY or the unified APM_API_KEY environment variable:

Quick Setup with CLI Command

The easiest way to configure TraceKit is using the interactive CLI command:

This command provides an interactive wizard that:

• Guides you through registration or API key setup
• Handles email verification flow (waits for your input)
• Automatically configures your .env file
• Tests the connection to verify everything works

Setup Options:

1. Easy Register - Automated registration with email verification
2. I have API key - Manual entry of existing API key

See the CLI Setup Wizard section below for detailed information.

💡 Usage

Automatic Integration

Once installed and configured, TraceKit automatically integrates with GEMVC:

1. Framework Initialization - The framework creates a TraceKitProvider instance via ApmFactory::create()
2. Root Trace Creation - A root span is automatically created for each HTTP request
3. Span Management - Child spans are created for database queries, controller operations, etc.
4. Trace Batching - Traces are automatically batched and sent every 5 seconds (configurable via APM_SEND_INTERVAL) using synchronous ApiCall
5. Shutdown Safety - All pending traces are sent immediately on shutdown to ensure no data loss

Manual Span Creation

You can create custom spans in your code:

Using TraceKit Toolkit

The TraceKitToolkit class provides client-side integration features:

CLI Setup Wizard

The tracekit init command provides an interactive setup wizard for configuring TraceKit:

What the wizard does:

1. Welcome Banner - Displays TraceKit features and welcome message
2. Configuration Detection - Checks for existing TraceKit configuration
   • If found, offers to reconfigure, test connection, or exit
3. Setup Method Selection:
   • Easy Register (Recommended)
     • Prompts for email and organization name
     • Sends registration request to TraceKit
     • Sends verification code to your email
     • Waits for you to enter the verification code (CLI does not exit)
     • Supports retry logic (max 3 attempts)
     • Automatically receives and saves API key
   • I have API key
     • Prompts for existing API key
     • Validates API key format
4. Service Name Setup - Prompts for unique service name with validation
5. Automatic Configuration - Updates .env file with:
   • TRACEKIT_API_KEY - Your API key
   • TRACEKIT_SERVICE_NAME - Your service name
   • APM_NAME="TraceKit" - Provider name
   • APM_ENABLED="true" - Enable APM
6. Connection Test - Verifies API key and connection to TraceKit service
7. Success Message - Displays confirmation and next steps

Example Flow:

Note: The CLI command is part of the GEMVC framework and uses standard CLI infrastructure (Command, CliBoxShow, ProjectHelper).

✨ Features

OpenTelemetry OTLP JSON Format

• Standard Format - Uses OpenTelemetry OTLP JSON format for compatibility
• Service Discovery - Automatically includes service name in resource attributes
• Span Hierarchy - Supports parent-child span relationships
• Event Recording - Can record exception events and custom events on spans

Batch Trace Sending

• Time-Based Batching - Uses AbstractApm's batching system to send traces in batches every 5 seconds (configurable via APM_SEND_INTERVAL)
• Synchronous ApiCall - Uses synchronous ApiCall for reliable trace delivery (compatible with OpenSwoole production environments)
• Automatic Batching - Multiple traces are automatically combined into single batch requests for efficiency
• Shutdown Safety - All pending traces are force-sent on shutdown to ensure no data loss
• Graceful Degradation - Failures in trace sending don't affect application performance
• OpenSwoole Compatible - No async operations that cause issues in OpenSwoole production environments

Span Management

• Stack-Based Context - Simple stack-based span context propagation
• Automatic Sampling - Respects sample rate configuration
• Error Handling - Errors are always traced (forced sampling)
• Span Kinds - Supports OpenTelemetry span kinds (SERVER, CLIENT, INTERNAL, etc.)

📖 API Reference

TraceKitProvider

Main provider class implementing ApmInterface (used by ApmFactory):

Instance Methods:

• init(array $config = []): bool - Initialize provider with configuration (for setup/configuration via CLI/GUI)
• isEnabled(): bool - Check if tracing is enabled
• startTrace(string $operationName, array $attributes = [], bool $forceSample = false): array - Start a root trace (span). $forceSample = true forces tracing regardless of sample rate (used for errors)
• startSpan(string $operationName, array $attributes = [], int $kind = self::SPAN_KIND_INTERNAL): array - Start a child span. $kind can be SPAN_KIND_SERVER, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, etc.
• endSpan(array $spanData, array $finalAttributes = [], ?string $status = self::STATUS_OK): void - End a span. $status can be STATUS_OK or STATUS_ERROR
• recordException(array $spanData, \Throwable $exception): array - Record an exception on a span. Auto-creates trace if no root span exists
• flush(): void - Add traces to batch queue (batches are sent automatically every APM_SEND_INTERVAL seconds)
• getTraceId(): ?string - Get current trace ID (inherited from AbstractApm)

Static Methods:

• getCurrentInstance(): ?TraceKitProvider - Get the current active instance
• clearCurrentInstance(): void - Clear the current active instance

Note: TraceKitModel is an alternative implementation with additional methods like addEvent(), getSampleRate(), getSampleRatePercent(), and getActiveSpan().

TraceKitToolkit

Client-side integration class implementing ApmToolkitInterface:

• registerService(string $email, ?string $organizationName, string $source, array $sourceMetadata): JsonResponse - Register new service
• verifyCode(string $sessionId, string $code): JsonResponse - Verify email and get API key
• getStatus(): JsonResponse - Check integration status
• sendHeartbeatAsync(string $status, array $metadata): void - Send asynchronous heartbeat
• getMetrics(string $window): JsonResponse - Get service metrics
• getAlertsSummary(): JsonResponse - Get alerts overview
• createWebhook(string $name, string $url, array $events, bool $enabled): JsonResponse - Create webhook

For complete API documentation, see the GEMVC APM Contracts README.

🔄 Related Packages

• gemvc/apm-contracts - Base APM contracts and interfaces
• gemvc/library - GEMVC core framework

🌐 Environment Variables Reference

Core APM Variables

• APM_NAME - APM provider name (must be "TraceKit" for this provider)
• APM_ENABLED - Enable/disable APM ("true", "1", "false", "0", or boolean)
• APM_SAMPLE_RATE - Sample rate for traces (0.0 to 1.0, where 1.0 = 100%)
• APM_TRACE_RESPONSE - Enable/disable response tracing
• APM_TRACE_DB_QUERY - Enable/disable database query tracing
• APM_TRACE_REQUEST_BODY - Enable/disable request body tracing
• APM_SEND_INTERVAL - Batch send interval in seconds (default: 5). Controls how often batched traces are sent to APM provider. Lower values = more frequent sends with smaller batches. Minimum: 1 second.
• APM_API_KEY - Unified API key (works for all providers)

TraceKit-Specific Variables

• TRACEKIT_API_KEY - TraceKit API key (or use APM_API_KEY)
• TRACEKIT_SERVICE_NAME - Service name for traces
• TRACEKIT_ENDPOINT - Override default endpoint URL (optional)
• TRACEKIT_SAMPLE_RATE - Override sample rate (optional)
• TRACEKIT_TRACE_RESPONSE - Override response tracing flag (optional)
• TRACEKIT_TRACE_DB_QUERY - Override DB query tracing flag (optional)
• TRACEKIT_TRACE_REQUEST_BODY - Override request body tracing flag (optional)

🧪 Development

Running Tests

All tests pass successfully (87 tests, 200 assertions). The test suite includes stub files for GEMVC framework classes to enable independent testing without requiring the full framework installation.

Code Quality

PHPStan passes with no errors at level 9. Stub files for GEMVC framework classes are automatically loaded via phpstan.neon configuration for static analysis.

Stub Files

This package includes stub files in the stubs/ directory for GEMVC framework classes. These stubs serve two purposes:

1. PHPStan Static Analysis - Loaded via phpstan.neon bootstrap configuration
2. PHPUnit Test Execution - Loaded via tests/bootstrap.php for runtime testing

The stub files provide minimal implementations with correct method signatures and type hints, allowing the package to be analyzed and tested independently.

⚖️ License

MIT License - see LICENSE file for details.

👥 Contributing

Contributions are welcome! Please see the GEMVC APM Contracts README for information about the APM provider architecture.

Credits

Part of the GEMVC PHP Framework built for Microservices ecosystem. made with love By Ali Khorsandfard