Skip to content

README.md

Latest commit

 

History

History
320 lines (253 loc) · 7.48 KB

README.md

File metadata and controls

320 lines (253 loc) · 7.48 KB

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