Getting Started

Minimal Setup

Installation
```
composer require instana/instana-php-opentracing
```
Add the autoloader to your project if not using PSR-4.

Basic Initialization Locate the InstanaTracer class and initialize it with your Instana agent configuration:

use Instana\InstanaTracer;

$tracer = InstanaTracer::getTracer(
    'your-instana-agent-host',
    42699, // Default Instana agent port
    'your-application-name',
    '1.0.0' // Application version
);

First Use Case: Instrumenting a Request Wrap your request handling logic in a span:

$span = $tracer->buildSpan('handle-request')->start();
try {
    // Your request logic here
    $result = doSomething();
} finally {
    $span->finish();
}

Where to Look First

Documentation: Check the Instana PHP OpenTracing docs for agent-specific setup.
Tracer Configuration: Review InstanaTracer::getTracer() parameters for customization (e.g., sampling rate, tags).
Span Context: Explore SpanContext for propagating traces across services (e.g., HTTP clients).
Span Types: Review updated InstanaSpanType methods (entryType(), localType(), exitType()) for semantic span classification.

Implementation Patterns

Workflow: Instrumenting a Laravel Controller

Middleware for Automatic Tracing Create middleware to auto-instrument requests:

namespace App\Http\Middleware;

use Closure;
use Instana\InstanaTracer;

class TraceRequests
{
    public function handle($request, Closure $next)
    {
        $tracer = InstanaTracer::getTracer(...);
        $span = $tracer->buildSpan('HTTP ' . $request->method() . ' ' . $request->path())
            ->withTag('http.method', $request->method())
            ->withTag('http.url', $request->fullUrl())
            ->start();

        try {
            return $next($request);
        } finally {
            $span->finish();
        }
    }
}

protected $middleware = [
    \App\Http\Middleware\TraceRequests::class,
];

Service-Level Instrumentation with Span Types Use semantic span types for better trace visualization:

$span = $tracer->buildSpan('fetch-user')
    ->asType(InstanaSpanType::exitType()) // Mark as external call
    ->start();
try {
    $user = User::find($id);
} finally {
    $span->finish();
}

Propagating Context Use SpanContext to pass traces to downstream services (e.g., HTTP clients):

$context = $span->getContext();
$client = new HttpClient();
$response = $client->request('GET', $url, [
    'headers' => [
        'uber-trace-id' => $context->getTraceId(),
    ],
]);

Integration Tips

Queue Workers: Instrument queue jobs by wrapping handle() in spans with appropriate types:

$span = $tracer->buildSpan('process-order')
    ->asType(InstanaSpanType::localType()) // Mark as internal processing
    ->start();
try {
    // Job logic
} finally {
    $span->finish();
}

Exceptions: Add error spans for unhandled exceptions:

try {
    // Logic
} catch (\Exception $e) {
    $span->log(['event' => 'error', 'message' => $e->getMessage()]);
    $span->setTag('error', true);
    throw $e;
}

Custom Metrics: Use Span::setTag() for business metrics (e.g., cart_items: 3).

Gotchas and Tips

Pitfalls

Agent Connectivity
- Issue: Spans may not appear in Instana if the agent is unreachable.
- Fix: Verify the agent host/port and network connectivity. Use InstanaTracer::getTracer() with false for the host to disable tracing (for testing).
Context Propagation
- Issue: Traces break if SpanContext isn’t propagated to downstream services.
- Fix: Ensure headers like uber-trace-id are forwarded in HTTP requests. Use libraries like opentracing-contrib/php-http for automatic propagation.
Sampling Rate
- Issue: High-volume apps may overwhelm Instana with too many spans.
- Fix: Configure sampling in InstanaTracer:
```
$tracer = InstanaTracer::getTracer(..., 0.1); // Sample 10% of traces
```
Span Lifecycle
- Issue: Unfinished spans (e.g., due to uncaught exceptions) create "orphaned" traces.
- Fix: Use finally blocks or Laravel’s illuminate/support/helpers:
```
$span = $tracer->buildSpan('task')->start();
try {
    // Work
} finally {
    $span->finish();
}
```
Deprecated Methods (v2.0.0)
- Issue: The package renamed InstanaSpanType::entry(), InstanaSpanType::local(), and InstanaSpanType::exit() to entryType(), localType(), and exitType() for PHP < 7 compatibility.
- Fix: Update all span type assignments to use the new method names:
```
// Old (deprecated in v2.0.0)
$span->asType(InstanaSpanType::entry());

// New (v2.0.0+)
$span->asType(InstanaSpanType::entryType());
```

Debugging

Check Tracer Status: Log the tracer’s active state:

\Log::debug('Tracer active:', ['active' => $tracer->isActive()]);

Span IDs: Log SpanContext to correlate traces:

\Log::debug('Trace ID:', [$span->getContext()->getTraceId()]);

Agent Logs: Check Instana agent logs (/var/log/instana/agent.log) for connection issues.

Extension Points

Custom Tags Extend InstanaTracer to add application-specific tags:
```
$span->withTag('user.role', auth()->user()->role);
```

Global Tracer Instance Bind the tracer to Laravel’s container for DI:

$app->singleton(InstanaTracer::class, function () {
    return InstanaTracer::getTracer(...);
});

Testing Mock the tracer in tests:

$this->app->instance(InstanaTracer::class, Mockery::mock(InstanaTracer::class));

Config Quirks

Environment Variables: Store agent host/port in .env:

INSTANA_AGENT_HOST=instana-agent
INSTANA_AGENT_PORT=42699

Then load them dynamically:

$tracer = InstanaTracer::getTracer(
    env('INSTANA_AGENT_HOST'),
    env('INSTANA_AGENT_PORT', 42699),
    ...
);

Span Type Usage Use semantic span types (entryType(), localType(), exitType()) to improve trace readability:
- entryType(): For incoming requests (e.g., HTTP endpoints).
- localType(): For internal processing (e.g., business logic).
- exitType(): For outgoing calls (e.g., database queries, API calls).
Deprecated Methods: Avoid using the old InstanaSpanType::entry(), InstanaSpanType::local(), and InstanaSpanType::exit() methods in new code. Update existing code to use the new method names.

Instana Php Opentracing Laravel Package