name: telemetry.capture
version: 0.1.0
description: >
  Captures and logs usage telemetry for Betty Framework components.
  Provides thread-safe JSON logging to /registry/telemetry.json with
  ISO timestamps and structured metadata.

inputs:
  - name: skill
    type: string
    required: true
    description: Name of the skill/component being logged (e.g., 'plugin.build', 'agent.run')

  - name: status
    type: string
    required: true
    description: Execution status (success, failure, timeout, error, pending)

  - name: duration_ms
    type: number
    required: true
    description: Execution duration in milliseconds

  - name: caller
    type: string
    required: true
    description: Source of the call (e.g., CLI, API, workflow.compose)

  - name: inputs
    type: object
    required: false
    default: {}
    description: Sanitized input parameters (no secrets)

  - name: error_message
    type: string
    required: false
    description: Error message if status is failure/error

  - name: metadata
    type: object
    required: false
    default: {}
    description: Additional context (user, session_id, environment, etc.)

outputs:
  - name: telemetry_entry
    type: object
    description: The captured telemetry entry with ISO timestamp

  - name: telemetry_file
    type: string
    description: Path to the telemetry.json file

dependencies: []

status: active

entrypoints:
  - command: /telemetry/capture
    handler: telemetry_capture.py
    runtime: python
    description: Capture telemetry event for a Betty component
    parameters:
      - name: skill
        type: string
        required: true
        description: Skill name
      - name: status
        type: string
        required: true
        description: Execution status
      - name: duration_ms
        type: number
        required: true
        description: Duration in milliseconds
      - name: caller
        type: string
        required: true
        description: Caller identifier
      - name: inputs
        type: string
        required: false
        description: JSON string of inputs
      - name: error_message
        type: string
        required: false
        description: Error message
    permissions:
      - filesystem:read
      - filesystem:write

tags:
  - telemetry
  - logging
  - observability
  - audit