FHIR Nursing API - Sistema de Observabilidade Completo

Este projeto implementa uma API FHIR para educação em enfermagem com sistema completo de observabilidade usando Grafana, Loki, Prometheus, Promtail e Jaeger.

🏗️ Arquitetura do Sistema

Componentes Principais

1. API FHIR (FastAPI)

   • Endpoints para casos clínicos, sessões de aprendizagem e avaliações
   • Integração com IA para análise clínica
   • Métricas customizadas para educação em enfermagem

2. Stack de Observabilidade

   • Prometheus: Coleta de métricas
   • Grafana: Dashboards e visualizações
   • Loki: Agregação de logs
   • Promtail: Coleta de logs
   • Jaeger: Tracing distribuído
   • AlertManager: Sistema de alertas

🚀 Deploy do Sistema

Pré-requisitos

• Docker e Docker Compose instalados
• Python 3.8+ (para desenvolvimento)
• Portas disponíveis: 3000, 8000, 9090, 3100, 14268, 16686

1. Iniciar Stack de Observabilidade

cd observability
docker-compose up -d

2. Verificar Serviços

# Status dos containers
docker-compose ps

# Logs dos serviços
docker-compose logs -f grafana
docker-compose logs -f prometheus

3. Iniciar API FHIR

# Em outro terminal
cd ../fhir-nursing-api
python main.py

🌐 URLs dos Serviços

Serviço	URL	Descrição
API FHIR	http://localhost:8000	API principal
Grafana	http://localhost:3000	Dashboards (admin/admin)
Prometheus	http://localhost:9090	Métricas e targets
Jaeger UI	http://localhost:16686	Tracing distribuído
AlertManager	http://localhost:9093	Gerenciar alertas

📊 Dashboards do Grafana

1. FHIR Nursing Overview

• Métricas gerais da API
• Requisições por endpoint
• Latência e erros
• Casos clínicos ativos

2. Student Competency Assessment

• Scores por competência
• Progresso dos estudantes
• Análise de sessões de aprendizagem
• Performance da IA

Importar Dashboards

1. Acesse http://localhost:3000 (admin/admin)
2. Vá para "+" → "Import"
3. Cole o JSON dos dashboards (já configurados nos arquivos)

📈 Métricas Customizadas

Métricas de Negócio

# Casos clínicos
fhir_metrics.clinical_cases_total
fhir_metrics.clinical_cases_created_total

# Sessões de aprendizagem
fhir_metrics.learning_sessions_active
fhir_metrics.learning_session_duration

# Competências
fhir_metrics.competency_scores
fhir_metrics.assessments_total

# IA
fhir_metrics.ai_inference_duration
fhir_metrics.ai_inferences_total

Métricas de Sistema

# HTTP
fhir_metrics.http_requests_total
fhir_metrics.http_request_duration

# Ações dos estudantes
fhir_metrics.student_actions_total
fhir_metrics.student_action_duration

🔍 Tracing Distribuído

Contextos Automaticamente Rastreados

• Requisições HTTP
• Operações de banco de dados
• Inferência de IA
• Avaliações de competência

Consultar Traces

1. Acesse http://localhost:16686
2. Procure por service "fhir-nursing-api"
3. Analise latência e dependências

📝 Logs Estruturados

Formato JSON

{
  "timestamp": "2023-12-01T10:30:00Z",
  "level": "INFO",
  "message": "Learning session started",
  "student_id": "student_123",
  "session_id": "session_456",
  "clinical_case_id": "case_001",
  "trace_id": "abc123",
  "event_type": "learning_session"
}

Tipos de Eventos

• learning_session: Início/fim de sessões
• student_action: Ações dos estudantes
• ai_inference: Processamento de IA
• competency_assessment: Avaliações
• api_request: Requisições HTTP
• system_event: Eventos do sistema

🚨 Alertas Configurados

Alertas de Performance

• Alta latência da API (>2s por 5min)
• Taxa de erro HTTP (>10% por 5min)
• Tempo de inferência IA (>10s por 5min)

Alertas de Sistema

• CPU alto (>80% por 10min)
• Memória alta (>80% por 10min)
• Espaço em disco (<10% disponível)

Alertas Educacionais

• Baixo score médio (<0.7 por 30min)
• Muitas sessões falhas (>5 por hora)

🧪 Testes da API

Health Check

curl http://localhost:8000/health

Métricas

curl http://localhost:8000/metrics

Casos Clínicos

# Listar casos
curl http://localhost:8000/api/v1/clinical-cases

# Obter caso específico
curl http://localhost:8000/api/v1/clinical-cases/case_001

Iniciar Sessão de Aprendizagem

curl -X POST http://localhost:8000/api/v1/learning-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "student_123",
    "clinical_case_id": "case_001"
  }'

Registrar Ação do Estudante

curl -X POST http://localhost:8000/api/v1/student-actions \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "student_123",
    "session_id": "session_id_aqui",
    "action_type": "assessment",
    "node_name": "vital_signs",
    "action_data": {"heart_rate": 80}
  }'

🔧 Desenvolvimento

Estrutura do Projeto

fhir-nursing-api/
├── main.py                    # Servidor principal
├── app/
│   └── monitoring/
│       ├── metrics.py         # Métricas Prometheus
│       ├── logging.py         # Logging estruturado
│       └── tracing.py         # Tracing distribuído
├── observability/
│   ├── docker-compose.yml     # Stack observabilidade
│   ├── prometheus.yml         # Config Prometheus
│   ├── alert_rules.yml        # Regras de alerta
│   ├── grafana/dashboards/    # Dashboards Grafana
│   └── loki-config.yaml       # Config Loki
└── logs/                      # Arquivos de log

Variáveis de Ambiente

# API
export API_HOST=0.0.0.0
export API_PORT=8000
export LOG_LEVEL=INFO

# Tracing
export JAEGER_ENDPOINT=http://localhost:14268/api/traces
export OTEL_SERVICE_NAME=fhir-nursing-api

# Métricas
export METRICS_ENABLED=true
export PROMETHEUS_PORT=9090

🐛 Troubleshooting

Problemas Comuns

1. Container não inicia

# Verificar logs
docker-compose logs nome_do_servico

# Verificar portas
netstat -tulpn | grep :3000

2. Métricas não aparecem

# Verificar targets no Prometheus
# http://localhost:9090/targets

# Verificar endpoint de métricas da API
curl http://localhost:8000/metrics

3. Dashboards vazios no Grafana

# Verificar data sources
# http://localhost:3000/datasources

# Verificar se API está enviando métricas
curl http://localhost:8000/health

4. Logs não aparecem no Loki

# Verificar Promtail
docker-compose logs promtail

# Verificar arquivos de log
ls -la logs/

📋 Checklist de Deploy

• Docker Compose rodando
• Todos os containers healthy
• API respondendo no /health
• Métricas disponíveis no /metrics
• Grafana acessível (admin/admin)
• Dashboards importados
• Prometheus coletando métricas
• Jaeger recebendo traces
• Alertas configurados
• Logs sendo coletados

🎯 Próximos Passos

1. Autenticação: Adicionar OAuth2/JWT
2. Banco de Dados: Migrar para PostgreSQL/MongoDB
3. IA Real: Integrar Ollama/OpenAI
4. CI/CD: GitHub Actions para deploy
5. Backup: Estratégia de backup dos dados
6. Scaling: Múltiplas instâncias da API
7. Segurança: HTTPS, rate limiting, validação

📞 Suporte

Para problemas ou dúvidas:

1. Verificar logs da aplicação
2. Consultar métricas no Grafana
3. Analisar traces no Jaeger
4. Revisar alertas no AlertManager