[WIP] Epic: OpenTelemetry (OTel) Integration

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original issue description:

Issue #585: OpenTelemetry (OTel) Integration

Scope: Telemetry and observability integration

Risk: Medium to high. May affect performance and logging.

Relevant files:

• src/shared/error/errorHandler.ts
• src/shared/observability/errorHandler.ts
• src/shared/observability/autoInstrumentation.ts
• src/shared/observability/metrics.ts
• src/modules/diet/food/infrastructure/supabaseFoodRepository.ts
• app.config.ts
• package.json
• docker-compose.observability.yml
• src/

Description:
The issue details roadmap, code examples, dependencies, and performance risks. Observability integration, affects error handler, logging, metrics, CI/CD. Incremental change, but requires careful rollout.

Acceptance Criteria:

• OTel is integrated and configured correctly
• No performance regressions due to OTel integration
• Logs and metrics are available and accurate
• Documentation is updated for OTel usage

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Epic: OpenTelemetry (OTel) Integration</issue_title>
<issue_description>## Issue #585: OpenTelemetry (OTel) Integration

Scope: Telemetry and observability integration

Risk: Medium to high. May affect performance and logging.

Relevant files:

• src/shared/error/errorHandler.ts
• src/shared/observability/errorHandler.ts
• src/shared/observability/autoInstrumentation.ts
• src/shared/observability/metrics.ts
• src/modules/diet/food/infrastructure/supabaseFoodRepository.ts
• app.config.ts
• package.json
• docker-compose.observability.yml
• src/

Description:
The issue details roadmap, code examples, dependencies, and performance risks. Observability integration, affects error handler, logging, metrics, CI/CD. Incremental change, but requires careful rollout.

Acceptance Criteria:

• OTel is integrated and configured correctly
• No performance regressions due to OTel integration
• Logs and metrics are available and accurate
• Documentation is updated for OTel usage</issue_description>

Comments on the Issue (you are @copilot in this section)

@marcuscastelo Previous description:

OpenTelemetry (OTel) Integration

The error handler design we implemented in #551 is fully compatible with OpenTelemetry (OTel). The architecture was structured to facilitate future integrations with observability systems.

🔄 OpenTelemetry Integration

1. Current Structure → OTel

// src/shared/error/errorHandler.ts - Current version
interface ErrorContext {
  component: string
  operation: string
  additionalData?: Record<string, any>
}

// Future version with OTel
import { trace, context } from '@opentelemetry/api'

interface ErrorContext {
  component: string
  operation: string
  additionalData?: Record<string, any>
  traceId?: string  // New field
  spanId?: string   // New field
}

2. Enhanced Error Handler with OTel

// src/shared/observability/errorHandler.ts
import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api'

export function handleApiError(
  error: Error,
  context: ErrorContext
): void {
  const tracer = trace.getTracer('marucs-diet')
  const span = tracer.startSpan(
    `error.${context.operation}`,
    {
      kind: SpanKind.INTERNAL,
      attributes: {
        'error.type': 'api_error',
        'error.component': context.component,
        'error.operation': context.operation,
        'error.message': error.message,
        ...context.additionalData
      }
    }
  )

  // Mark span as error
  span.setStatus({
    code: SpanStatusCode.ERROR,
    message: error.message
  })

  // Record error event
  span.addEvent('error.occurred', {
    'error.stack': error.stack,
    timestamp: Date.now()
  })

  // Structured logging (compatible with current implementation)
  console.error(`[${context.component}] ${context.operation} failed:`, {
    error: error.message,
    traceId: span.spanContext().traceId,
    spanId: span.spanContext().spanId,
    ...context.additionalData
  })

  span.end()
}

3. Automatic Instrumentation

// src/shared/observability/autoInstrumentation.ts
import { NodeSDK } from '@opentelemetry/auto-instrumentations-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { JaegerExporter } from '@opentelemetry/exporter-jaeger'

const sdk = new NodeSDK({
  traceExporter: new JaegerExporter({
    endpoint: process.env.JAEGER_ENDPOINT
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-http': {
        enabled: true,
      },
      '@opentelemetry/instrumentation-fetch': {
        enabled: true,
      }
    })
  ]
})

sdk.start()

4. Instrumented Usage Example

// src/modules/diet/food/infrastructure/supabaseFoodRepository.ts
import { trace } from '@opentelemetry/api'
import { handleApiError } from '~/shared/observability/errorHandler'

export async function fetchFoodById(id: number): Promise<Food | null> {
  const tracer = trace.getTracer('marucs-diet')
  
  return tracer.startActiveSpan('food.fetch_by_id', async (span) => {
    span.setAttributes({
      'food.id': id,
      'operation.type': 'database.query'
    })

    try {
      const result = await supabase
        .from('foods')
        .select('*')
        .eq('id', id)
        .single()

      if (result.error) throw new Error(result.error.message)
      
      span.setStatus({ code: SpanStatusCode.OK })
      return result.data
      
    } catch (error) {
      // Current handler + OTel integration
      handleApiError(error as Error, {
        component: 'SupabaseFoodRepository',
        operation: 'fetchFoodById',
        additionalData: { foodId: id }
      })
      
      return null
    } finally ...

</details>
Fixes marcuscastelo/macroflows#585

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/marcuscastelo/macroflows/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 13 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/marcuscastelos-projects?upgradeToPro=build-rate-limit

[vercel]

Deployment failed with the following error:

Too many requests - try again in 1 minute (more than 60, code: "api-deployments-flood").

Learn More: https://vercel.com/docs/limits#rate-limits