Você deixa um agente investigando um bug, põe um segundo para mapear os testes, um terceiro para revisar a documentação e ainda sobe a aplicação e os logs em painéis separados.

Poucos minutos depois, começa a saga:

• Abre o primeiro terminal — nada mudou;
• Abre o segundo — o agente terminou há três minutos e você não viu;
• Abre o terceiro — ele está parado desde o início, esperando uma aprovação sua.
• Etc…

Rodar vários agentes de IA é fácil, o difícil é saber qual deles precisa da sua atenção no momento! O tempo que você gasta descobrindo, terminal a terminal, qual deles precisa de você agora é uma perca de produtividade. Cada verificação é uma troca de contexto — e a maioria não encontra nada.

O Herdr ataca exatamente essa parte. Ele mantém agentes e outros processos em uma interface persistente e concentra, em uma barra lateral, o estado de cada um: quem está trabalhando, quem terminou e quem depende de uma decisão sua.

Ele não distribui tarefas, não evita conflitos no Git e não substitui Codex, Claude Code ou qualquer outro agente. Seu papel é organizar e tornar observável o ambiente onde esses agentes trabalham — para que rodar cinco não seja mais caótico do que rodar um.

Neste guia você percorre tudo na prática: sobe vários agentes em paralelo, usa os estados como fila de atenção, age só onde é necessário, sai sem interromper nada e volta para a mesma sessão. No fim, um bloco de dicas para escalar isso sem se perder.

Um mapa rápido antes de começar

O Herdr tem quatro níveis. Vale fixá-los agora, porque os passos seguintes usam esses termos:

• Sessão: o ambiente persistente mantido pelo servidor do Herdr.
• Workspace: o espaço de um projeto, repositório, worktree ou investigação.
• Aba: uma separação de contexto dentro do workspace.
• Painel: um terminal real, onde roda um agente ou qualquer outro comando.

Guardadas essas quatro palavras, o resto do fluxo é intuitivo.

O que muda em relação a tmux ou Zellij?

tmux e Zellij resolvem muito bem a persistência de terminais: painéis, processos vivos, detach e reattach. O Herdr parte da mesma base, mas trata alguns desses processos como o que eles são — agentes de IA — e mostra o estado de cada um.

A diferença cabe em uma frase: tmux e Zellij mantêm os terminais vivos; o Herdr também diz quais deles pedem uma ação sua.

Antes de começar

Você precisa de um terminal, um projeto local e pelo menos um agente de programação instalado — Codex ou Claude Code, por exemplo. Dá para subir duas instâncias do mesmo agente; não é preciso instalar ferramentas diferentes para experimentar o fluxo.

Git não é necessário para o primeiro teste. Ele passa a importar quando dois ou mais agentes podem alterar o projeto ao mesmo tempo.

Mãos à obra: vários agentes em paralelo

1. Instale e abra a ferramenta

No Linux ou macOS, use o instalador oficial:

curl -fsSL https://herdr.dev/install.sh | sh

Também é possível instalar com Homebrew ou mise:

brew install herdr

mise use -g herdr

No Windows, o suporte nativo ainda está em beta e utiliza o canal preview:

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

Abra um novo terminal se o comando ainda não estiver no PATH. Depois, entre no projeto e inicie o Herdr:

cd ~/projetos/meu-projeto
herdr

Em uma sessão vazia, o primeiro workspace é criado automaticamente.

Uma nota sobre atalhos:quase todos começam com o prefixo Ctrl+B. Você pressiona Ctrl+B, solta as teclas e então pressiona a próxima tecla. Daqui em diante, escrevo apenas "Ctrl+B depois V".

Antes de subir os agentes, vale um aviso sobre flexibilidade: o Herdr funciona sem nenhum arquivo de configuração, mas deixa você adaptar quase tudo quando quiser:

• temas, cores e alternância entre modos claro e escuro;
• atalhos e comandos personalizados;
• largura, conteúdo e ordenação da barra lateral;
• shell e diretório inicial de novos painéis;
• diretório usado para criar worktrees;
• comportamento das conexões remotas.

Você pode abrir as configurações direto pela interface (Ctrl+B depois S) ou ver todas as opções em texto com herdr --default-config e editar ~/.config/herdr/config.toml.

Depois de editar o arquivo, aplique a maioria das mudanças sem reiniciar os painéis:

herdr server reload-config

Nada disso é necessário para começar — volte a esta seção quando quiser afinar a experiência.

2. Suba os agentes

No painel aberto, execute o agente como faria em qualquer terminal:

claude

Dê a ele uma tarefa segura e somente de leitura:

Sem alterar arquivos ou executar comandos destrutivos, descreva a
estrutura deste projeto e explique como a aplicação é iniciada localmente.

Enquanto ele processa, a barra lateral o mostra como working.

Divida o painel à direita com Ctrl+B depois V (ou clique com o botão direito no painel). No novo painel, suba outra instância:

claude

Dê a ela uma tarefa diferente, ainda sem escrita:

Sem alterar arquivos, aponte onde estão os testes, como executá-los
e quais partes importantes parecem sem cobertura.

Repita mais uma ou duas vezes — um agente para revisar a documentação, outro para propor um refactor, todos em modo somente leitura por enquanto:

Sem alterar arquivos, liste inconsistências e trechos desatualizados
na documentação do projeto.

Agora há três ou quatro agentes no mesmo workspace. Este é o momento em que, sem o Herdr, começaria a saga de abrir um terminal atrás do outro. Com ele, você olha uma coluna só!

3. Use os estados como fila de atenção

A barra lateral não é uma lista de terminais; é uma fila de prioridade. Cada agente carrega um estado:

• blocked: Precisa de resposta, aprovação ou decisão. Abra-o primeiro.
• done: Terminou e você ainda não viu o resultado. Revise a saída e as possíveis alterações.
• working: Está executando a tarefa. Normalmente, deixe-o trabalhar.
• idle: Está aguardando, ou você já viu a conclusão.Retome quando fizer sentido.
• unknown: O Herdr não classificou o estado com segurança. Verifique o painel diretamente.

Os estados não seguem uma ordem fixa: um agente pode ir direto para done; outro pode parar no meio para pedir autorização ou esclarecer o escopo. Por isso, uma regra resolve quase tudo:

Primeiro blocked, depois done. O resto raramente precisa de você.

Com quatro agentes, a fila de atenção se parece com isto:

Agente A · bug        working ───────────────► done  ── revisar
Agente B · testes     working ─► blocked ─► você responde ─► working
Agente C · docs       working ─────────────────────────► done
Agente D · refactor   working ───────────────────────────────►
Você                  sobe todos ─► lê a sidebar ─► trata blocked, depois done

Repare que você nunca abriu os agentes A e D enquanto trabalhavam: a coluna já dizia que não precisavam de você. Esse é o ganho central — o Herdr não decide por você, mas derruba o custo de descobrir onde a decisão é necessária.

Deixe o Herdr chamar você de volta

O recurso que mais mudou meu fluxo foi poder largar os agentes trabalhando e ir fazer outra coisa. Quando um deles termina ou trava, o Herdr toca um som ou exibe uma notificação — não preciso manter o terminal em primeiro plano nem revisar os painéis o tempo todo.

As notificações visuais têm quatro modos de entrega:

Para receber uma notificação do sistema quando um agente em segundo plano terminar ou pedir atenção, ajuste as configurações.

Há duas formas de fazer isso: pela interface, com Ctrl+B depois S, ou editando o arquivo ~/.config/herdr/config.toml:

[ui.toast]
delivery = "system"
delay_seconds = 2

[ui.sound]
enabled = true

O atraso evita alarme para mudanças de estado muito rápidas: o Herdr só notifica se o agente ainda estiver no mesmo estado quando o intervalo terminar.

Juntas, sidebar e notificação fecham o ciclo de atenção: a barra lateral mostra onde agir quando você está no Herdr; a notificação chama você de volta quando está em outra coisa.

Dicas de produtividade para rodar muitos agentes com ainda mais produtividade

O básico acima escala bem, mas alguns hábitos fazem diferença quando o número de agentes cresce:

1. Trabalhe pela fila. Só abra blocked e done. Enquanto um agente estiver working, confie na coluna e siga no seu painel.
2. Ordene a barra lateral por estado. Deixe blocked e done no topo — eles sobem sozinhos para onde seu olho já está. (Rode herdr --default-config para ver a chave exata.)
3. Nomeie abas e painéis. “testes”, “docs” e “refactor” em uma lista de oito agentes valem muito mais que oito claude idênticos. (clique com botão direito em cima e vá na opção “rename”)
4. Mantenha servidor, testes e logs ao lado. Os painéis são terminais reais: deixe a aplicação, os testes e os logs em abas próprias, junto dos agentes, e você acompanha tudo sem trocar de janela.
5. Dê escopo e permissões na própria tarefa. Quanto mais claro o pedido e quanto mais cedo você autoriza o que é seguro, menos vezes o agente volta para blocked no meio do caminho.
6. Confie na notificação para trocar de contexto de verdade. Largue os agentes, vá para outra atividade e deixe o Herdr chamar você.
7. Um escritor por worktree. É a regra que mantém o paralelismo seguro quando os agentes passam a alterar arquivos — detalhada logo adiante.

Indo além do básico

Os recursos a seguir entram em cena quando você passa de “experimentando” para “usando no dia a dia”: agentes que escrevem código, trabalho em máquina remota, restauração de sessões e automação.

Pule à vontade se ainda está conhecendo a ferramenta.

Uma worktree para cada escritor

O Herdr facilita subir vários agentes, mas não torna seguro que todos alterem a mesma árvore de trabalho. Mesmo com arquivos diferentes, eles podem executar formatadores, atualizar dependências, gerar migrations, mexer em snapshots ou manipular o index do Git.

Adote uma regra simples:

Uma worktree pode ter vários agentes somente de leitura, mas no máximo um agente com permissão de escrita.

Para criar uma worktree manualmente:

git worktree add ../meu-projeto-tarefa-a -b tarefa/a main

Isso cria outro diretório, ligado ao mesmo repositório, com branch e arquivos independentes. No Herdr, Ctrl+B depois Shift+G inicia o fluxo de criação de uma worktree a partir do workspace selecionado.

Um fluxo seguro é:

1. O agente A investiga e implementa uma mudança na worktree dele.
2. Servidor e testes rodam dentro dessa mesma worktree.
3. Havendo um diff, outro agente pode revisá-lo em modo somente leitura.
4. Uma segunda mudança independente ganha outra worktree e outra branch.
5. Você revisa os resultados e decide o que integrar.

Worktrees isolam arquivos e branches, não responsabilidades. Antes de soltar dois escritores, você ainda precisa explicar, em uma frase, a fronteira entre as tarefas.

Trabalho remoto por SSH

Execute o Herdr na máquina onde estão o código, os processos e as credenciais:

ssh usuario@servidor
cd /caminho/do/projeto
herdr

Faça detach com Ctrl+B depois Q, encerre a conexão SSH e retorne quando quiser:

ssh usuario@servidor
herdr

Também é possível conectar um cliente local direto a um servidor remoto:

herdr --remote <host>

O modelo serve bem a tarefas demoradas: os processos seguem na máquina remota mesmo quando seu computador local se desconecta.

Automação e diagnóstico

A personalização você já viu na instalação. Faltam dois recursos mais avançados — deixar um agente operar o próprio Herdr e diagnosticar estados classificados errado:

Para deixar um agente controlar painéis, ler saídas e aguardar processos, instale a skill oficial em agentes compatíveis:

npx skills add ogulcancelik/herdr --skill herdr -g

Domine primeiro o ciclo agente → estado → decisão → detach → retorno. A automação deve ampliar um fluxo que você já compreende, não substituí-lo.

Se um agente aparecer com o estado errado, confira a integração e peça ao Herdr que explique a classificação:

herdr integration status
herdr agent explain <target>

Se necessário, atualize as regras de detecção com herdr server update-agent-manifests. O estado blocked é deliberadamente conservador, e uma interface nova pode aparecer como idle até que seu padrão seja reconhecido.

Quando o Herdr vale a pena?

Se você usa um único agente e acompanha cada execução até o fim, seu terminal atual provavelmente basta.

O Herdr passa a fazer diferença quando:

• dois ou mais agentes trabalham ao mesmo tempo;
• agentes, servidor, testes, logs (etc…) convivem juntos no seu workspace;
• você perde tempo verificando abas que não mudaram;
• tarefas demoradas precisam continuar depois de fechar o terminal;
• o trabalho acontece em uma máquina remota por SSH.

Para avaliar a ferramenta, faça um teste pequeno:

• abra um projeto;
• suba dois ou três agentes somente de leitura;
• acompanhe blocked e done pela barra lateral;
• confirme se você sabe, de imediato, qual agente precisa de atenção.

Se a resposta estiver à vista sem percorrer vários terminais, o Herdr já resolveu sua dor principal!

Fontes oficiais

• Site do Herdr
• Documentação
• Instalação
• Quick start
• Conceitos e estados dos agentes
• Agentes e detecção de estados
• Comparação com outras ferramentas
• Integrações
• Estado e restauração de sessões
• Trabalho remoto
• Configuração
• Referência completa de configuração
• Skill para agentes
• Solução de problemas

Herdr: a solução para gerenciar vários agentes de IA sem perder o controle was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Introdução

Quando falamos em Kotlin Multiplatform (KMP), um dos desafios é organizar o código de forma que possamos compartilhar lógica entre diferentes plataformas (Android, IOS).
Nesse cenário, o uso de Injeção de Dependência (DI) ajuda a manter o projeto escalável, testável e limpo.

Neste artigo, vou mostrar como utilizei o Koin em um app simples de lista de tarefas, desenvolvido em KMP, para gerenciar dependências como repositories, usecases e viewmodels.

2. O que é Injeção de Dependência?

Injeção de Dependência é um padrão de projeto que delega a criação das dependências para um componente externo, em vez de a própria classe instanciá-las. Isso aplica o princípio da Inversão de Dependência, garantindo que módulos dependam de abstrações e não de implementações concretas.

Benefícios:

— Desacoplamento: Classes conhecem interfaces/abstrações, não implementações concretas.

— Testabilidade: Fica fácil trocar uma implementação real por um mock/fake nos testes.

— Composição centralizada: Criação e configuração de objetos fica em um único lugar (modules).

— Reuso e manutenção: Mudar implementações (ex: trocar cliente HTTP) sem mexer no código consumidor.

— Gerência de ciclo de vida: O container controla singletons, factories e scopeds:

• Singleton → Uma instância global criada apenas uma vez.
• Factory → Uma nova instância a cada uso.
• Scoped → Uma instância por ciclo de vida específico (sessão, activity, etc.).

3. Como o koin funciona?

1) Módulos e definições

• Módulo (module {...}) é onde você declara definitions: single {...}, factory {...}, scoped {...}, viewModel {...} etc.
• Cada definição descreve como construir um tipo/serviço. O Koin constrói o grafo lendo os módulos na inicialização.
• Dentro das definições você pode usar get() para solicitar ao Koin uma instância já registrada no grafo, permitindo compor objetos a partir de suas dependências sem criá-los manualmente.

Exemplo :

val appModule = module {

    factory { AddTaskUseCase(customKoin.koin.get<TaskRepository>()) }
    factory { RemoveTaskUseCase(customKoin.koin.get<TaskRepository>()) }
    factory { GetTasksUseCase(customKoin.koin.get<TaskRepository>()) }

    viewModel<TaskViewModel> {
        TaskViewModel(
            addTaskUseCase = get(),
            removeTaskUseCase = get(),
            getTasksUseCase = get()
        )
    }
}

2) Inicialização: startKoin / KoinApplication / GlobalContext

No Android, a forma mais comum de inicializar o Koin é dentro da classe que estende Application. Assim, o container de DI(Dependency Injection) é configurado logo no início do ciclo de vida do app e fica disponível em toda a aplicação.

Exemplo:

class TaskApp : Application() {    
    override fun onCreate() {        
        super.onCreate() 
        startKoin { 
            androidContext(this@TaskApp)            
            modules(appModule)        
        }
    } 
}

O que acontece aqui

• startKoin{...} inicializa o container de Injeção de Dependências (Dependency Injection) e registra o contexto global do Koin via GlobalContext.
  A partir desse ponto que o Koin passa a gerenciar e fornecer as instâncias definidas nos seus módulos.
• androidContext(this@TaskApp) esta linha informa ao Koin qual é o Context global da aplicação Android.
• Integração com ViewModel do AndroidX, já que o Koin precisa conhecer o ciclo de vida e o contexto do app.
• modules(appModule) carrega as definições de dependências que você declarou no módulo appModule.

Em resumo: Sem o androidContext, o Koin enxerga apenas as definições puras de Kotlin. Ao fornecê-lo, você conecta o container de DI ao ambiente Android, habilitando recursos extras como: módulos Android (androidModule), integração com viewModel{...}e a possibilidade de injetar classes que dependem diretamente do framework Android.

No IOS (Kotlin Multiplatform), não há Application, então o Koin é inicializado manualmente dentro do código compartilhado (geralmente em initKoin()), e essa função é chamada a partir do código Swift no início da execução do app.
Assim, o container também fica disponível para o restante da aplicação IOS.

Exemplo (Kotlin — módulo compartilhado — Helper.kt):

fun initKoin(){
    startKoin {
        modules(appModule)
    }
}

Exemplo (Swift — iOS App):

@main
struct iOSApp: App {
    init() {
        HelperKt.doInitKoin()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Depois da inicialização, qualquer classe que implemente KoinComponent pode usar:

val repo: TaskRepository by inject()

ou diretamente:

val repo = get<TaskRepository>()

3) Alternativa: contextos isolados com KoinApplication

Normalmente, quando você chama startKoin { ... }, o Koin cria um contexto global de injeção de dependências (GlobalContext). Isso funciona bem para apps comuns, mas em alguns cenários você pode precisar evitar esse contexto global:

• Bibliotecas/SDKs: se sua lib usa Koin internamente, não é uma boa prática registrar módulos direto no contexto global do app, pois pode gerar conflitos de nomes/tipos com o app principal.
• Múltiplos contextos separados: em casos mais avançados, você pode querer rodar dois contêineres de DI(dependency injection) distintos (ex.: testar dois ambientes diferentes, “mock” vs “real”, ou isolar dependências de um módulo específico).

Nesses casos, em vez de usar startKoin, você pode criar um contexto local com koinApplication { ... }.

Exemplo:

val libraryModule = module {
    single<MyService> { MyServiceImpl() }
}
// Cria uma instância local e independente do Koin,
// útil para uso em bibliotecas sem depender do contexto global.
val customKoin = koinApplication {
    modules(libraryModule)
}
val service = customKoin.koin.get<MyService>()

O que este código faz:

• koinApplication { ... } cria uma instância independente de KoinApplication.
• Você acessa as dependências usando customKoin.koin.get<T>() em vez de get() global.
• Esse contêiner não interfere no startKoin do app principal — ou seja, app e lib podem coexistir sem conflitos.

4) E como seria a injeção de dependencia do repository como singleton sem o uso de frameworks?

object ServiceLocator {  
    val taskRepository: TaskRepository by lazy {  
        TaskRepositoryImpl()  
    }
    
    fun provideTaskViewModel(): TaskViewModel {  
        return TaskViewModel(repository = taskRepository)  
    }  
}

Como seria usado:

val viewModel = ServiceLocator.provideTaskViewModel()

O que este código faz:

• ServiceLocator funciona como um mini container criado por você.
• by lazy garante que TaskRepositoryImpl() só será instanciado uma vez (similar com o single do Koin).
• Quando precisar de um TaskViewModel, você chama provideTaskViewModel(), que passa o repository correto.

5) Qual é a principal diferença prática entre factory e single?

• Factory

O factory cria sempre um novo repositório a cada navegação, então os registros anteriores não são mantidos na memória — ao voltar, a lista de tarefas está zerada.

No código:

val appModule = module {
    factory<TaskRepository> { TaskRepositoryImpl() }

    viewModel<TaskViewModel> {
        TaskViewModel(repository = get())
    }
}

• Single

O single garante que o TaskRepository seja compartilhado entre telas, mantendo as tarefas vivas na memória durante toda a navegação — diferente do factory, onde os dados se perdem a cada nova instância.

No código:

val appModule = module {
    single<TaskRepository> { TaskRepositoryImpl() }
    viewModel<TaskViewModel> {
        TaskViewModel(repository = get())
    }
}

6) Teste unitários

• Código de produção (com Koin)

interface TaskRepository {
    fun all(): List<Task> 
}

class TaskRepositoryImpl : TaskRepository {  
    private val items = mutableListOf<Task>()
    override fun all(): List<Task> = items.toList()
}

class TaskViewModel constructor(
  private val repository: TaskRepository
): ViewModel() {
    private val scope = CoroutineScope(Dispatchers.Default)
    private val _tasks = MutableStateFlow<List<Task>>(emptyList())
    val tasks: StateFlow<List<Task>> get() = _tasks

    private fun loadTasks() {
        scope.launch {
            _tasks.value = repository.all()
        }
    }
}

val appModule = module {
    single<TaskRepository> { TaskRepositoryImpl() }
    
    viewModel<TaskViewModel> {
        TaskViewModel(repository = get())
    }
}

• Teste com Koin

Com Koin, você pode sobrescrever os módulos reais dentro do teste:

class TaskViewModelTest : KoinTest {
    private val testModule = module(override = true) {
           single<TaskRepository> { FakeTaskRepository() }
    }
    
    @Before
    fun setup() {
        startKoin {
            modules(testModule)
        }
    }
    
    @After
    fun teardown() {
        stopKoin()
    }
    @Test
    fun `loadTasks deve retornar lista fake`() {
        val expectedList = listOf("Tarefa falsa 1", "Tarefa falsa 2")
        val viewModel: TaskViewModel by inject()
        val result = viewModel.loadTasks()
        assertEquals(expectedList, result)
    }
}

• Teste sem Koin (injeção manual)

Se você não tivesse Koin, teria que criar manualmente o ViewModel com uma fake/mock

class FakeTaskRepository : TaskRepository {
    override fun all() = listOf("Tarefa falsa 1", "Tarefa falsa 2")    
}

@Test
fun `loadTasks deve retornar lista fake`() {
    val expectedList = listOf("Tarefa falsa 1", "Tarefa falsa 2")
    val fakeRepository = FakeTaskRepository()
    val viewModel = TaskViewModel(fakeRepository)
    val result = viewModel.loadTasks()
    assertEquals(expectedList, result)
}

4. Vantagens do Koin frente a outras bibliotecas de DI

O Koin se destaca por várias razões no ecossistema Kotlin e KMP:

• Sintaxe Kotlin-first e DSL intuitiva — o Koin foi feito para Kotlin, usando sua linguagem de forma fluida, sem depender de muitas anotações ou boilerplate.
• Sem geração de código obrigatória — diferentemente de frameworks como Hilt ou Dagger que dependem de processamento de anotação e arquivos gerados, o Koin resolve o grafo em tempo de execução, o que simplifica o setup e agiliza o desenvolvimento.
• Leveza e agilidade — Menos configuração, menos boilerplate e maior rapidez para começar a usar no projeto. Isso favorece a produtividade, especialmente em apps que vão evoluir ou que têm múltiplas plataformas.
• Compatível com Kotlin Multiplatform (KMP) — O Koin funciona bem em projetos multiplataforma, o que o torna mais adequado para um cenário onde você compartilha lógica entre Android e IOS.
• Flexibilidade para testes — A simplicidade dos módulos e do container torna mais fácil sobrescrever dependências em testes unitários ou configurar versões diferentes para diferentes ambientes.

5. Como seria na prática com KMP?

1. Configuração

libs.versions.toml

[versions]  
koin = "4.1.1"

[libraries]  
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }  
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }  
koin-androidx-compose = { module = "io.insert-koin:koin-androidx-compose", version.ref = "koin" }

2. Projeto simples

interface TaskRepository {  
    fun add(todo: Task)
    fun remove(id: String)
    fun all(): List<Task> 
}

class TaskRepositoryImpl : TaskRepository {  
    private val items = mutableListOf<Task>()
    override fun add(todo: Task) { items.add(todo) }
    override fun remove(id: String) { items.removeAll { it.id == id } }
    override fun all(): List<Task> = items.toList()
}

class TaskViewModel constructor(
  private val repository: TaskRepository
): ViewModel() {
    private val scope = CoroutineScope(Dispatchers.Default)
    private val _tasks = MutableStateFlow<List<Task>>(emptyList())
    val tasks: StateFlow<List<Task>> get() = _tasks
    
    init {
        loadTasks()
    }
    
    fun addTask(title: String) {
        scope.launch {
            repository.add(Task(randomString(), title))
            loadTasks()
        }
    }
    
    fun removeTask(id: String) {
        scope.launch {
            repository.remove(id)
            loadTasks()
        }
    }
    
    private fun loadTasks() {
        scope.launch {
            _tasks.value = repository.all()
        }
    }
}

val appModule = module {
    single<TaskRepository> { TaskRepositoryImpl() }
    viewModel<TaskViewModel> {
        TaskViewModel(repository = get())
    }
}

Injeção de depência no Android

class TaskApp : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
           androidContext(this@TaskApp)
           modules(appModule)
        }
    }
}

Injeção de depência no IOS

helper.kt

fun initKoin(){
    startKoin {
        modules(appModule)
    }
}

iOSApp.swift

@main
struct iOSApp: App {
    init() {
        HelperKt.doInitKoin()
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

3. Pontos relevantes

• Mantenha sua lógica multiplataforma (commonMain) desacoplada da API do framework: preferível usar constructor injection em classes do commonMain para não acoplar o código à API do Koin.
• Inicialização: normalmente você declara os modules no commonMain (dependências comuns) e inicia o Koin no código de plataforma (Android, iOS), adicionando módulos específicos de plataforma (ex.: engines do Ktor, implementações nativas).
• Teste no commonMain: como seu commonMain fica desacoplado, fica fácil trocar módulos por test modules em testes de unidade multiplataforma.
• Limite o uso de by inject() ou KoinComponent ao código da camada extrema(UI por exemplo), não no core da lógica de negócio, dessa forma, o domínio permanece independente de frameworks e testável, enquanto o Koin atua apenas como um orquestrador na borda do sistema.
• Use qualifiers quando tiver múltiplas implementações do mesmo tipo (ex.: named("local") / named("remote")).
• Evite singletons mutáveis — prefira objetos imutáveis ou providers/factories para evitar problemas em Kotlin/Native.
• Teste com módulos de substituição (override) para trocar impls reais por fakes/mocks.

4. Anti-patterns

• Service Locator como padrão: chamar GlobalContext.get().get() em todo o lugar esconde dependências e dificulta testes.
• Exposição do container em camadas internas: não passe o container pelo modelo/domain.

class SaveTaskUseCase(private val container: Koin) {
    fun execute(task: Task) {
        val repository: TaskRepository = container.get()
        repository.save(task)
     }
}

• Singletons globais com estado: podem criar acoplamento e problemas de concorrência (especialmente em Kotlin/IOS Native).
• Misturar muitos papéis em um módulo: módulos inchados dificultam mocks em testes.

6. Estrutura do Projeto

Abaixo está uma representação visual da estrutura de pastas do projeto KMP utilizado para demonstrar o uso do Koin na injeção de dependências.
A organização segue os princípios de Clean Architecture, separando claramente as camadas de data, domain, presentation, injection e navigation, dentro do módulo commonMain.

7. Conclusão

A Injeção de Dependência (DI) no Kotlin Multiplatform vai além de simplificar a criação de objetos: ela garante que sua base de código permaneça desacoplada, testável e escalável entre diferentes plataformas.

O Koin se destaca nesse contexto porque combina simplicidade com flexibilidade. No commonMain, podemos manter a lógica de negócio limpa, orientada a interfaces e livre de referências diretas ao framework.

Além disso, o Koin facilita a troca de implementações em testes, reduz o boilerplate em comparação com um ServiceLocator manual e oferece controle refinado de ciclo de vida (single, factory, scoped). Porém, é importante evitar anti-padrões como o uso excessivo do GlobalContext ou a criação de singletons mutáveis em Kotlin/Native.

Em resumo, a melhor prática no KMP é:

• manter o commonMain desacoplado e limpo;
• inicializar e compor dependências nas plataformas;
• usar o Koin como suporte estratégico para bootstrap, composição e testes.

Assim, seu código ganha clareza, reuso e facilidade de manutenção em projetos multiplataforma de qualquer porte.

8. Referências

• Documentação oficial do Koin
• Compose Multiplatform Docs
• Koin no GitHub
• Exemplo de projeto com Koin + KMP + compose multiplatform (GitHub)

Injeção de Dependências com Koin no Kotlin Multiplatform (KMP) was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

E neste artigo, quero compartilhar a visão de bastidores (com a minha minha opinião) de como essa transição tem acontecido na prática: decisões técnicas, aprendizados, desafios e como conseguimos entregar mais com menos.

Se você já pensou em usar KMP ou está apenas curioso para entender como uma migração desse nível funciona no dia a dia aqui vai um relato real, com bastidores técnicos e dicas que podem evitar armadilhas no seu projeto.

Ei… Alguns assuntos e discussões que embasaram decisões dariam artigos próprios (e alguns pretendo escrever em breve, contando mais detalhes sobre), mas neste texto vou focar nos pontos principais que guiaram essa transformação e dicas rápidas com exemplo sobre o código. Bora nessa?

1. De onde partimos

De forma super resumida, a Fretebras conecta caminhoneiros a transportadoras. Durante muito tempo, o público-alvo usava majoritariamente Android, e por isso, o app era inteiramente nativo e estava disponível apenas para o Android. Os usuários de dispositivos iOS tinham apenas a opção de uma versão Web com funcionalidades limitas.

Com o crescimento do uso de iOS nesse público, surgiu a necessidade e oportunidade de oferecer uma experiência mobile-first.

Diante disso, avaliamos as opções: manter versões nativas, usar tecnologias crossplataforma ou apostar no compartilhamento de código.

Entre as avaliações decidimos seguir com o KMP, mas, calma, vamos entrar nos detalhes dessa decisão.

2. Por que migrar para KMP?

1. O app Fretebras era 100% Kotlin, com ~90% das telas em Jetpack Compose (MVVM + uma boa cobertura de testes unitários).
2. Aproveitar a expertise existente, tínhamos um chapter composto por pessoas com domínio do ecossistema Android e Kotlin
3. Reaproveitamento de código, muito código, ViewModels, UseCases, Repositories e UI em Compose.
4. Entregar mais rápido, evitar retrabalho em features duplicadas para o iOS.

3. A transição em três fases

Fundação

• Criamos um time específico para estruturar e construir a base.
• Nosso foco foi criar APIs que tornassem o desenvolvimento KMP praticamente indistinguível do Android reduzindo a carga cognitiva dos times de produto.
• Escrevemos classes e objetos com APIs similares às que já usávamos no Android. (Mas sem um Context God)

Integração

• Lançamos um MVP por volta de setembro de 2024.
• Começamos a integrar o chapter: talks, trilhas, base de conhecimento, pair programming e o início da disseminação de tarefas.
• Também realizamos overviews técnicos, escrita de documentações internas e mantivemos um diálogo contínuo.

Avaliação

• Com o KMP em produção, passamos a focar na identificação de oportunidades de melhoria. Automatizamos a coleta de métricas de desenvolvimento.
• Usamos ferramentas como o Konsist (Tipo um linter pra estrutura do projeto) para metrificar o esforço técnico da migração por feature/fluxo.
• Delegamos via chapter as adaptações para as squads, para tentar ser transparente com o produto. 👀

4. Princípios de código que fizeram diferença

1. Clean Architecture, SOLID e MVVM: adotamos esses pilares, criando mecanismos que garantem sua adoção, simplificando assim a transição. Adotando esses princípios, grande parte do código pode ser reaproveitada, aplicando apenas pequenas adaptações.
2. Desacoplamento de APIs de plataforma: nada de Context em composables. (Eu sei, de forma única isso não é um problema, mas conforme o projeto escala, numericamente, se torna uma coisa a mais pra resolver)
3. Testes unitários em primeiro lugar: isso nos deu segurança para modularizar e portar ViewModels, UseCases e Repositories de forma quase instantânea.

5. Priorize Bibliotecas KMP‑friendly

Priorize dependências que sejam Kotlin‑first, e de preferência já compatíveis com KMP. A tabela a seguir mostra as opções que adotamos e o que elas substituem no Android.

🧈 Dica de ouro: sempre esconda dependências atrás de interfaces.

6. Automatize mais e cobre menos

Use linters estruturais como o Konsist para garantir que as definições e práticas sejam seguidas, e assim delegar menos coisas para revisão manual. Automatize o que for possível e fizer sentido para garantir que o projeto está caminhando na direção esperada, adicione uma checagem e veja se o código novo está sendo testado, use a criatividade.

import com.lemonappdev.konsist.api.assertions.*
import com.lemonappdev.konsist.api.ext.*
import org.junit.Test

class DomainNoAndroidImportsTest {
    @Test
    fun `domain não deve importar pacotes Android`() {
        Konsist
            .scopeFromProject()
            .files
            .filter { it.resideInPath("..domain..")
            .assertTrue { 
                it.imports.none { it.hasNameContaining("android")
             }
    }
}

Se algum arquivo do módulo domain importar android.* ou androidx.*, o build falha.

7. Desafios

Apesar dos benefícios, o uso do KMP também trouxe desafios. Por ser uma tecnologia ainda em evolução, a documentação oficial nem sempre refletia a realidade prática (também vale pra libs da comunidade). Em vários momentos seguimos a documentação da JetBrains, mas na hora da implementação, exigiam ajustes ou os famosos workarounds 😜.

7.1 Tipos genéricos em Flows no iOS

No iOS, por exemplo, ainda não temos uma geração estável de código Swift direto a partir do KMP. Isso nos obrigou a criar soluções internas, binds, mappers e coisas do tipo.

Um exemplo clássico e conhecido é a interoperabilidade com o Objective-C/Swift: quando se exporta um Flow<T>, o tipo T se perde no binding e vira Flow<Any?>.

Uma dica que facilitou bastante: use o SKIE, uma biblioteca que gera wrappers e binds para o Swift de forma eficiente e estável.

// Declaração no código kotlin compartilhado (common main)
object FlowContainer {
  val myFlow: Flow<MyCustomType> = ...
}

Sem SKIE:

// Swift - erro de compilação
let mapped = FlowContainer.myFlow.map { value in
    // ❌ error! 'Flow' has no member 'map'
}

// myFlow é exposto como Kotlinx_coroutines_coreFlow

Com SKIE, Flow vira AsyncSequence<T> e o uso fica nativo:

// Swift (com SKIE) - myFlow vira AsyncSequence<MyCustomType>
Task {
    for try await item in FlowContainer.myFlow {
        // ✅ Uso nativo de AsyncSequence
        print(item)
    }
}

// É possível encadear operadores
let cancellable = FlowContainer.myFlow
    .map(\.property)
    .sink { result in
        print(result)
    }

// myFlow agora é AsyncSequence<MyCustomType>

7.2 Falta de suporte de libs oficiais

Muitas libs super usadas no ecossistema android atualmente não possuem suporte oficial ao KMP, e isso pode te afastar do KMP, mas não deixe que isso te assuste, toda lib nativa ainda pode ser usada no seu projeto. Por exemplo, veja como é possível usar o remote config:

// No código kotlin compartilhado, defina uma interface comum
interface RemoteConfigProvider {
    suspend fun getString(key: String): String
    suspend fun getBoolean(key: String): Boolean
}

Implementações para Android (Firebase) e iOS:

// no androidMain, estenda a interface e forneça os resultados necessários
class AndroidRemoteConfigProvider(
    private val remoteConfig: FirebaseRemoteConfig = FirebaseRemoteConfig.getInstance()
) : RemoteConfigProvider {

    override fun getString(key: String) = remoteConfig.getString(key)

    override fun getBoolean(key: String) = remoteConfig.getBoolean(key)
}

Do lado do iOS você tem duas opções, estender a interface ainda em kotlin no iosMain, ou estenda-la no swift e fornecer essa implementação via injeção de dependências. Por exemplo, estendendo no swift e usando koin:

import ComposeApp
import FirebaseRemoteConfig

// estenda sua interface 
class IOSRemoteConfigProvider : RemoteConfigProvider {

  let remoteConfig = RemoteConfig.remoteConfig()

  func getString(key: String) -> String {
    return remoteConfig.configValue(forKey: key).stringValue ?? ""
  }

  ...
}

// No swift appDelegate ou algum outro lugar pra iniciar o seu DI container
DIContainer.initModules(
  remoteConfigProvider: { IOSRemoteConfigProvider() } 
)

No iosMain, forneça uma forma acessível do swift passar as suas dependências nativas resolvidas via interface

// iosMain
object DIContainer {

  fun initModules(
    remoteConfigProvider: () -> RemoteConfigProvider
  ) {
    initKoin {
      module {
        single<RemoteConfigProvider> {
          remoteConfigProvider()
        }
      }

      // seus outros módulos
      // ...
    }
  }
}

// Agora você pode usar o remoteConfig em qualquer lugar
// do seu código kotlin compartilhado
class Sample : KoinComponent {
  private val remoteConfig by inject<RemoteConfigProvider>()
}

8. Lições aprendidas

• Construa APIs amigáveis para quem já programa para o Android; o iOS vira bônus.
• Automatize o que puder e fizer sentido, use Konsist, linters e outros, alivie o code‑review.
• Testes automatizados são a rede de segurança e na migração vão dar mais confiança ao time.
• Esteja preparado para workarounds, mas deixe documentado e tente remover assim que possível.
• Respeite a arquitetura definida desde o início, manter as camadas bem separadas evita acoplamentos, reduz suas dívidas e torna a troca de implementações muito mais simples.
• O ecossistema do KMP avança, desafios que ontem exigiam workarounds recebem correções ou soluções quase diariamente e de forma constante, não tenha medo.

Conclusão

A jornada aqui na Fretebras com Kotlin Multiplatform e a transição continua, mas até aqui os resultados são verdadeiramente incríveis! Conseguimos evitar retrabalho, aumentar a velocidade de entrega e manter uma base de código consistente entre Android e iOS.

Claro, houveram desafios, documentação incompleta, bibliotecas sem suporte, workarounds necessários. Mas cada obstáculo trouxe aprendizados valiosos, que hoje nos permitem evoluir mais rápido e com mais confiança.

Se você trabalha com mobile, se está aprendendo ou sua empresa está pensando em migrar para KMP, espero que esse relato ajude a clarear os caminhos, evitar armadilhas e de certa forma, inspirar e embasar boas decisões.

Se quiser bater um papo ou trocar ideias, me chama no LinkedIn ou comenta aqui 👇

— — — — — — —
Pedro Henrique Cardoso — LinkedIn/pedro-hcardoso
Senior Android Developer at Fretebras

A jornada da Fretebras com Kotlin Multiplatform (KMP): desafios e aprendizados was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Esses dias, um desenvolvedor me procurou com uma dúvida curiosa: o problema de CORS na aplicação já havia sido resolvido, mas ele continuava tomando erro de CORS no navegador.
Fui investigar, e achei que valia compartilhar aqui o que descobri — até porque pode ser útil para outros também.

(Disclaimer: este texto foi escrito com a ajuda do ChatGPT, ajustado para o contexto da Fretebras.)

O que é CORS?

CORS (Cross-Origin Resource Sharing) é uma proteção que o navegador aplica para evitar que aplicações web façam requisições para domínios diferentes do seu sem autorização explícita.

Ou seja: mesmo que o servidor responda corretamente, o navegador pode bloquear a resposta se os cabeçalhos de CORS não estiverem certos.

O que aconteceu?

O servidor já estava configurado para permitir as requisições, mas o navegador do dev continuava barrando por CORS.
O motivo? Cache de preflight.

O navegador tinha guardado uma resposta antiga de uma requisição OPTIONS (a chamada preflight), que dizia que o acesso não era permitido. Mesmo depois da correção no servidor, o navegador ainda confiava na resposta antiga.

Como funciona o OPTIONS?

Antes de certas requisições (por exemplo, POSTs com cabeçalhos customizados), o navegador envia automaticamente uma requisição OPTIONS para perguntar ao servidor:

“Eu posso fazer essa requisição?”

Se o servidor responde positivamente, o navegador segue para a requisição real. Se não, ele bloqueia.

Essa resposta pode incluir o cabeçalho Access-Control-Max-Age, que diz por quanto tempo o navegador pode confiar nessa autorização sem perguntar de novo.

Como funciona o cache?

Se o servidor responde, por exemplo, com:

Access-Control-Max-Age: 3600

O navegador entende que pode usar essa autorização por 3600 segundos (1 hora). Durante esse período, ele não reenvia o preflight.

O problema é que, se o servidor mudar a configuração durante esse tempo, o navegador não sabe — ele continua confiando na resposta antiga até o cache expirar.

Isso explica porque o desenvolvedor ainda via o erro, mesmo depois da correção.

Como corrigir

Abra as Ferramentas para Desenvolvedores pressionando F12
Com as Ferramentas para Desenvolvedores abertas, clique com o botão direito do mouse no botão "Recarregar" (o ícone de seta circular na barra de endereço).
No menu de contexto que aparece, selecione "Limpar cache e recarregar forçosamente"

Em resumo

• O CORS é uma proteção do navegador, não do servidor.
• O navegador pode cachear a autorização de CORS com base no preflight (OPTIONS).
• Mudanças no servidor podem não ser percebidas imediatamente por quem tem cache armazenado, ou seja, o desenvolvedor não consegue invalidar o cache do lado do usuário
• Soluções possíveis incluem forçar o refresh (limpar cache) ou usar Access-Control-Max-Age menores.

Pre-flight, CORS e como eles impactam usuários was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Se você está começando a desenvolver aplicativos Android com Jetpack Compose, provavelmente já ouviu falar sobre gerenciamento de estado. Mas como organizar sua lógica de forma clara, previsível e escalável? Uma abordagem poderosa é usar o padrão baseado em State, Event e Effects. Neste artigo, vou te mostrar como funciona esse padrão, por que ele é útil e como implementá-lo em um exemplo prático: um contador simples.

O que são State, Event e Effects?

Antes de mergulharmos no código, vamos entender os conceitos:

• State: Representa o estado atual da sua interface de usuário (UI). É como uma “fotografia” do que está sendo exibido na tela em um dado momento.
• Event: São as ações ou intenções do usuário, como clicar em um botão ou digitar algo. Eles dizem à lógica do aplicativo o que o usuário quer fazer.
• Effects: Efeitos colaterais que não pertencem ao estado principal, como exibir uma mensagem temporária (Snackbar), Toast ou navegar para outra tela, por exemplo.

Esse trio forma um fluxo unidirecional: os eventos fluem “para cima” (da UI para a lógica), o estado flui “para baixo” (da lógica para a UI), e os efeitos são tratados separadamente. Esse padrão é inspirado em arquiteturas como MVI (Model-View-Intent) e Unidirectional Data Flow (UDF), mas vamos mantê-lo simples e prático.

Por que usar esse padrão?

• Clareza: O fluxo de dados é previsível e fácil de entender.
• Testabilidade: A lógica fica isolada, facilitando testes unitários.
• Escalabilidade: Adicionar novas funcionalidades é mais organizado.

Agora, vamos colocar a mão na massa com um exemplo.

Exemplo: Um Contador com Jetpack Compose

Vamos criar um aplicativo de contador com dois botões: “Incrementar” e “Decrementar”. Sempre que o usuário clicar em um botão, o contador será atualizado e uma mensagem temporária será exibida.

Passo 1: Definindo State, Event e Effects

Primeiro, criamos as estruturas básicas em Kotlin:

• CounterState: Armazena o valor atual do contador.
• CounterEvent: Define as ações possíveis (incrementar ou decrementar).
• CounterEffect: Representa o efeito colateral de mostrar uma mensagem.

Passo 2: Criando a ViewModel

A ViewModel é onde a mágica acontece. Ela processa os eventos, atualiza o estado e emite efeitos. Usaremos StateFlow para o estado e SharedFlow para os efeitos.

Por que usar StateFlow para o estado?

StateFlow é ideal para armazenar e expor o estado porque:

• Mantém o último valor: Sempre guarda o estado mais recente, garantindo que qualquer nova coleta tenha acesso ao estado atualizado imediatamente.
• É observável e reativo: Quando o valor muda, todos os coletores ativos são notificados automaticamente.
• Evita repetições desnecessárias: Se o mesmo estado for emitido novamente, ele não notifica os coletores, otimizando o fluxo de dados.

Isso faz com que StateFlow seja perfeito para representar a UI, pois a UI precisa apenas do estado mais atual e deve ser atualizada automaticamente quando ele mudar.

Por que usar SharedFlow para os efeitos?

SharedFlow é mais adequado para efeitos porque:

• Não mantém estado: Diferente do StateFlow, ele não guarda o último valor emitido. Isso é essencial para efeitos transitórios como exibir um Snackbar ou navegar para outra tela.
• Pode reemitir eventos múltiplas vezes: Como efeitos precisam ser acionados sempre que ocorrem (e não apenas quando há uma mudança de estado), SharedFlow permite essa emissão contínua.
• Suporta diferentes estratégias de buffer e replay: Podemos configurar o SharedFlow para reemitir eventos recentes se necessário.

Se usássemos StateFlow para os efeitos, o Snackbar poderia ser reexibido desnecessariamente ao recompor a UI, o que não é o comportamento desejado.

Aqui, a ViewModel:

• Mantém o estado em _state e o expõe como um StateFlow.
• Emite efeitos em _effect usando um SharedFlow.
• Atualiza o estado e emite efeitos com base nos eventos recebidos.

Passo 3: Construindo a UI com Compose

Agora, criamos o Composable que consome o estado, envia eventos e lida com efeitos:

• collectAsStateWithLifecycle(): Observa o estado e atualiza a UI automaticamente.
• LaunchedEffect: Escuta os efeitos e exibe uma Snackbar quando necessário.
• Eventos: Enviados para a ViewModel via onEvent.

Como Tudo Funciona Junto?

1. O usuário clica em “Incrementar”.
2. Um evento CounterEvent.Increment é enviado para a ViewModel.
3. A ViewModel atualiza o estado (count + 1) e emite um efeito (ShowMessage).
4. O Composable reflete o novo estado (mostra o contador atualizado) e exibe a Snackbar com a mensagem.

Esse fluxo unidirecional mantém a lógica limpa e previsível.

Benefícios e Quando Usar

Esse padrão é ótimo para:

• Aplicativos com muitas interações de usuário.
• Projetos que precisam de testes robustos.
• Equipes que querem um código mais organizado.

Se o seu aplicativo for muito simples (como uma tela estática), talvez não valha a pena tanta estrutura. Mas, para algo mais complexo, como um formulário ou uma lista dinâmica, ele brilha.

Conclusão

Usar State, Event e Effects com Jetpack Compose é uma maneira elegante de gerenciar sua UI. Ele combina bem com as ferramentas modernas do Android, como StateFlow e SharedFlow, e segue os princípios recomendados pelo Google. Experimente no seu próximo projeto e veja como ele pode simplificar sua vida como desenvolvedor!

Se quiser aprofundar, confira a documentação oficial do Jetpack Compose ou explore bibliotecas como Orbit MVI. Happy coding!

Usando State, Event e Effects com Jetpack Compose: Um Guia Prático was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introdução

Nessa sequencia de artigos, vamos entender o conceito de Feature Store, o cenário onde se aplica e o uso na prática com o Feast, uma plataforma open-source de feature store projetada para gerenciar e armazenar as features, que utilizaremos no treinamento e inferência de um modelo de Machine Learning.

O que são features?

Features, ou características em português, são as variáveis ou atributos usados como entrada para os modelos. Elas representam os aspectos relevantes dos dados que o modelo utiliza para fazer previsões ou classificações. A qualidade e relevância das features são cruciais para o desempenho de qualquer modelo.

Exemplos de Features:

Features para um modelo de previsão de preços de imóveis:

• Área do imóvel
• Número de quartos
• Localização
• Ano de construção

As Features podem ser numéricas, representando valores contínuos ou discretos, como idade e salário. As categóricas são qualitativas e não ordenadas, como cor dos olhos ou país, enquanto as binárias possuem apenas dois valores, como sim/não. Features temporais capturam dados relacionados ao tempo, como datas e horários. Já as textuais são convertidas em números para uso nos modelos, como vetores ou embeddings. Cada tipo contribui de forma distinta para o desempenho do modelo.

O que é Feature Store?

Feature Store é um sistema de armazenamento e gerenciamento de dados, a fim de centralizarmos e organizarmos features, características de entidades, que são utilizadas por modelos de machine learning.

Imagine uma linha do tempo de uma entidade fictícia, onde ao longo do tempo foram coletadas algumas features, como no exemplo abaixo:

Onde podemos representar essas features em forma de tabela:

Nessa tabela podemos observar cada uma das nossas features ao longo do tempo. Podemos organizar as features a fim de configurarmos para uso via Feature Store, onde encontramos três tipos de colunas:

Sendo elas a partição por data e hora, identificador da entidade e as features em si, onde a partição se trata do campo de timestamp que registra o momento do estado da entidade, em seguida o identificador da entidade e por fim as features da entidade.

Que problema ela resolve?

As Features ficam armazenadas de forma distribuida, entre banco de dados de diferentes microserviços e fluxo de dados de streaming, elas precisam ser combinadas e conciliadas para gerar previsões precisas e serem entregues em baixa latência, viabilizando seu uso em iniciativas como recomendação ou detecção de fraude em tempo real, por exemplo.

Com as features centralizadas em uma Feature Store, isso nos permite que as equipes colaborem e compartilhem features entre as iniciativas. Reduzindo o retrabalho e acelerando o desenvolvimento de projetos de machine learning, além de possibilitar o versionamento, governança e controle de qualidade das features.

A Feature Store pode ser utilizada tanto em treinamento de modelos de ML por meio de features Offline, quanto em inferências em modelos de ML com features Online, ou seja, features Real-time em baixa latência.

O uso da Feature Store para treinamento de modelos de ML, buscamos as features da entidade a partir da data que desejarmos, onde obtemos como retorno o estado atual das features nessa data. Por exemplo, a entidade com ID 1234 em 2009 teria a Profissão "Estudante do Fundamental" e residente da cidade de "Esteio", obtendo as features de maneira histórica.

E o uso da Feature Store para inferência, buscamos as features da entidade a partir da data atual, onde obtemos como retorno o estado atual das features. Por exemplo, a entidade com ID 1234 atualmente teria a Profissão "Engenheiro de ML" e residente da cidade de "Porto Alegre", obtendo as features em baixa latência.

Cenário de Uso

Imagine uma empresa de e-commerce com diversos microserviços, cada um gerenciando uma parte específica do processo de vendas: gerenciamento de estoque, informações de produtos, perfil de usuário, histórico de compras, entre outros. Cada microserviço possui seu próprio banco de dados, onde armazena dados específicos relevantes para suas operações.

Além disso, o sistema de e-commerce processa dados de comportamento de usuário em tempo real, como visualizações de produtos e cliques, transmitidos em um fluxo contínuo (streaming) a partir de eventos gerados pelos usuários no site.

Essas features, distribuídas entre bancos de dados de diferentes microserviços e o fluxo de dados de streaming, precisam ser combinadas e conciliadas para gerar previsões precisas e entregues em baixa latência, onde podemos utilizar em iniciativas de recomendações de produtos ou detecção de fraudes em tempo real, por exemplo.

Caso as aplicações não estejam preparadas para retornar as informações necessárias, cenário comum de ocorrer, isso vai demandar semanas ou meses de trabalho entre times. Ao fim das integrações, estaremos sujeito ao tempo de latência para obter essas informações, onde dependendo do cenário como recomendação ou fraude o tempo completo de resposta idealmente deve ser na casa de milissegundos ou máximo poucos segundos.

Além disso, acabamos criando uma dependência gigante entre as aplicações e times, caso seja necessário levar em consideração uma feature extra para a realização de um teste AB, isso resultar em semanas de implementação da feature nova. Onde ao fim da implementação pode ser que ela não seja tão performática quanto o esperado 😅.

Por fim, acabamos entrando nesse ciclo de dependência para evoluirmos a performance do Modelo de ML, podendo impactar diretamente o potencial obtido com a inteligência e onerando o tempo de reação da inteligência a novos comportamentos e fluxos do negócio.

Feature Store

A Feature Store tem como objetivo centralizar e conciliar essas informações históricas e em tempo real.

Dados Históricos (Offline Store)

Os dados das fontes de streaming ou em batch são ingeridos e periodicamente extraídos, transformados e disponibilizadas na Offline Store da Feature Store. Uma vez que esses dados estão processados, estão disponíveis para consumo histórico para treinamento de modelos de ML.

Dados Real-time (Online Store)

As features processadas na Offline Store podem ser disponibilizadas em baixa latência na Online Store, sendo que as features disponibilizadas serão sempre o último estado da entidade.

As features podem ser disponibilizadas via materialização ou diretamente integradas a esteira de ingestão de dados de streaming, disponibilizando o estado mais recente das features em tempo real.

Materialização

A materialização ocorre quando queremos atualizar as features da Online Store a partir das features da Offline Store, ou seja, atualizar as features que estão sendo entregues em baixa latência para modelos ML baseados na participação de tempo ou novas entidades, atualizando o estado mais recente das features da entidade.

A materialização ocorre periodicamente conforme a necessidade do negócio, é comum que features cadastrais como endereços, documentos e dados pessoais dificilmente são alteradas com frequência, nesse cenário a materialização poderia acontecer de forma diária, a fim de atualizar as features do estado da entidade.

Com isso, é comum o uso de ETL ou Cron para realizar o gatilho da materialização das features, sendo o estado mais recente da entidade para a Online Store.

Cenário com Feature Store

Com isso, chegamos no diagrama acima, sendo um diagrama completo contemplando as aplicações, banco de dados, ingestão e disponibilização desses dados via Datalake.

Onde a Feature Store, atende tanto o time de Ciência de Dados com features processadas para treinamento de modelos a partir da Offline Store, nesse caso, o nosso Datalake. Quanto as features utilizadas para a inferência de modelos, sendo entregues em baixa latência a partir da Online Store.

Com esse diagrama, todas as integrações que antes seriam necessárias para realizar a integração com o modelo de ML, a fim de obter todas as features para realizar a inferência, deixam de ser necessárias.

Para realizar a integração com o modelo de ML vão ser necessárias apenas as features de gatilho, como identificadores das entidades. Todas as demais features necessárias para a inferência serão obtidas pelo modelo via Feature Store em baixa latência a partir dos identificadores das entidades, por fim realizando a inferência junto ao modelo.

Conclusão

A Feature Store tem como objetivo base fornecer features para treinamento de modelos de ML e inferência. Ela não é uma bala de prata, a Feature Store necessita de uma esteira de ingestão e arquitetura de dados madura, isso inclui monitoramento para garantir sua estabilidade e escalabilidade.

Além disso, talvez a necessidade mais importante é um processo maduro de contrato de dados entre times de dados e tecnologia. Pois, o papel que anteriormente era exercido pelos times de tecnologia de buscar, integrar e conciliar os dados, agora é exercido pelo time dados, onde qualquer tipo de mudança no contrato de dados sem planejamento pode comprometer a esteira de ingestão e disponibilização desses dados.

Caso ocorra a quebra de contrato, compromete primeiramente a ingestão, no caso de dados Offline, como features cadastrais que já ocorre uma materialização de forma periódica para a Online Store, o impacto ainda pode ser minimizado. Mas no cenário de ingestão de streaming, um processo de recomendação pode ter sua performance diretamente impactada caso a localização obtida pela entidade seja com delay de 1 hora atrás, por conta de uma atualização de contrato de dados não planejada.

Com isso, a responsabilidade de manter a ingestão e os contratos de dados é compartilhada entre times de dados e tecnologia. Mas a responsabilidade de manter o monitoramento e escalabilidade da Feature Store é do time de MLOps, por meio de processos para inclusão de features e monitoramento para manter a qualidade das features armazenadas.

Dessa forma, a Feature Store tem potencial para se tornar uma peça chave da plataforma de MLOps, permitindo acelerarmos o processo de evolução de modelos de ML e desenvolvimento de novos projetos. Além de se adaptar rapidamente com novos fluxos e comportamentos da jornada do usuário na plataforma.

Conquistando independência com relação as features, permitindo uma evolução continua do modelo e sua performance, sem necessariamente novas integrações com os times de tecnologia, acelerando o desenvolvimento de modelos de ML.

Na parte 2 dessa sequência de artigos, vamos utilizar na prática o Feast como Feature Store, para treinarmos e realizarmos a inferência de um modelo de Machine Learning.

Obrigado pela sua atenção! E até breve 😄

Feature Store (Parte 1): Acelerando o Desenvolvimento de Modelos de Machine Learning was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introdução

Ao trabalhar em um projeto Kotlin Multiplatform, me deparei com um desafio interessante: como manipular imagens de forma eficiente em diferentes plataformas, mantendo o código compartilhado limpo e sustentável? Este foi um problema real que encontrei durante o desenvolvimento, e precisei implementar uma solução prática e multiplataforma para lidar com imagens — algo comum em muitos aplicativos modernos.

A necessidade surgiu quando tive que lidar com imagens carregadas de strings Base64, convertê-las para byte arrays para envio via API e, por fim, renderizá-las na UI tanto em Android quanto em iOS. Cada plataforma tem suas particularidades, e eu queria evitar duplicação de código e garantir consistência no comportamento da aplicação.

Foi nesse cenário que desenvolvi a solução BitmapWrapper, utilizando o poder do expect/actual do Kotlin para criar uma camada de abstração, facilitando o trabalho com imagens independentemente da plataforma. Neste artigo, vou compartilhar como cheguei à implementação dessa solução, os desafios que encontrei no caminho, e como você pode aplicá-la nos seus projetos multiplataforma.

Solução com BitmapWrapper

Quando me deparei com o desafio de manipular imagens multiplataforma, sabia que precisaria encontrar uma forma de unificar a lógica entre Android e iOS, sem comprometer a flexibilidade que cada plataforma exige. Foi nesse contexto que surgiu a ideia de criar a classe BitmapWrapper.

Minha primeira necessidade era manipular imagens de maneira eficiente: carregar de Base64, converter para bytes e renderizar na UI. A ideia era encapsular as diferenças entre Bitmap no Android e UIImage no iOS, mantendo o código compartilhado limpo. Então, parti para criar uma expect class, que seria implementada de forma específica para cada plataforma.

O Papel da BitmapWrapper

A classe BitmapWrapper serve como uma abstração para a manipulação de imagens. Em vez de lidar diretamente com Bitmap no Android ou UIImage no iOS, encapsulamos esses objetos nativos dentro da BitmapWrapper. Isso nos permite trabalhar com um único tipo no código compartilhado, sem precisar conhecer os detalhes de implementação de cada plataforma.

Conversão Base64 para Imagem: fromBase64

A função fromBase64 transforma uma string Base64 em uma instância de BitmapWrapper, permitindo carregar uma imagem de forma consistente. Cada plataforma tem sua própria maneira de decodificar strings Base64 e convertê-las em objetos de imagem.

Conversão de Imagem para ByteArray: BitmapWrapper.toByteArray

A função toByteArray converte a imagem encapsulada em um array de bytes. Isso é útil quando precisamos serializar a imagem para enviar em uma API ou armazená-la no banco de dados local. O formato de bytes pode variar (PNG, JPEG, etc.), dependendo das necessidades do projeto.

Implementação Android

No Android, utilizamos a classe Bitmap, que representa uma imagem em memória. A conversão entre formatos é facilitada pela API de compressão e decodificação do BitmapFactory.

Detalhes Técnicos:

• Base64: A classe Base64 do Android facilita a decodificação da string.
• BitmapFactory: Usada para converter o array de bytes decodificado em uma imagem.
• ByteArrayOutputStream: Utilizado para comprimir o Bitmap em um formato como PNG ou JPEG e obter o array de bytes.

Implementação iOS

Com base nos aprendizados da comparação entre as plataformas, implementei a classe BitmapWrapper no código compartilhado e criei as funções específicas para cada plataforma. Para o Android, o processo foi relativamente simples, utilizando Bitmap e suas funções de conversão. No iOS, no entanto, tive que lidar com alguns detalhes mais específicos, especialmente na conversão de uma UIImage para um array de bytes.

Conversão de Imagem para ByteArray no iOS

Uma das partes mais desafiadoras foi a implementação da função toByteArray no iOS. Diferente do Android, que tem o método compress() para converter o Bitmap diretamente, no iOS precisei usar a função UIImageJPEGRepresentation() para obter os dados da imagem no formato JPEG. Aqui está o código que implementei:

Detalhes Técnicos:

• NSData: Utilizado para manipular dados binários no iOS, como a conversão de Base64 para uma imagem.
• UIImagePNGRepresentation: Função que converte um UIImage em dados PNG.
• Platform-Specific Logic: No iOS, trabalhamos diretamente com NSData para manipular binários e UIImage para a exibição de imagens.

Considerações Multiplataforma

A chave para entender essa solução é a maneira como o Kotlin Multiplatform isola o código específico de cada plataforma, mantendo a interface pública limpa e consistente. No código compartilhado, não precisamos saber como cada plataforma lida com imagens; apenas interagimos com a API do BitmapWrapper, e o compilador cuida de ligar as implementações corretas para cada plataforma.

Vantagens e Desafios

Vantagens

• Unificação da Lógica: O BitmapWrapper abstrai a complexidade, permitindo que desenvolvedores de diferentes plataformas trabalhem com imagens sem se preocupar com as particularidades de cada sistema operacional.
• Flexibilidade: Como cada plataforma pode ter necessidades específicas, a implementação actual permite ajustes finos, como o formato de compressão de imagem ou decodificação de Base64.
• Redução de Código Duplicado: Compartilhar a lógica comum em KMP evita a duplicação de código e facilita a manutenção.

Desafios

• Diferenças de API entre as Plataformas: Android e iOS têm APIs bastante diferentes para manipulação de imagens, o que pode exigir mais ajustes na implementação específica.
• Suporte de Recursos: Algumas plataformas podem ter funcionalidades extras ou limitações que precisam ser consideradas no desenvolvimento de soluções multiplataforma.

Conclusão

O Kotlin Multiplatform oferece uma maneira eficiente de compartilhar lógica entre Android e iOS, especialmente para funcionalidades complexas como a manipulação de imagens. A solução apresentada, utilizando BitmapWrapper com expect/actual, permite a manipulação de imagens de maneira consistente, seja carregando-as de Base64, convertendo-as para bytes ou renderizando-as na UI. Com essa abordagem, conseguimos aproveitar o melhor de cada plataforma, mantendo o código compartilhado limpo e extensível.

Considerações Finais

Essa foi a solução que apliquei para resolver o problema de manipulação de imagens no meu projeto. No entanto, sei que existem outras abordagens possíveis, e estou totalmente aberto a discussões sobre alternativas ou melhorias para esse processo. Se você tem alguma sugestão ou outra experiência para compartilhar, adoraria ouvir e trocar ideias!

Manipulação de Imagens no Kotlin Multiplatform com BitmapWrapper: Minha Experiência na… was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Na linguagem Go, a forma como organizamos campos em structs pode impactar significativamente o uso de memória e o desempenho do seu programa. Isso se deve aos conceitos de alinhamento de memória e padding, que garantem que os processadores acessem dados de forma eficiente.

O Que é Alinhamento de Memória?

Alinhamento de memória refere-se à disposição dos dados na memória física, de modo que possam ser acessados rapidamente. Cada tipo de dado tem um requisito de alinhamento baseado em seu tamanho. Por exemplo, um int64 deve começar em um endereço que seja um múltiplo de 8 bytes. Este alinhamento é crítico para que o processador manipule os dados com o mínimo de operações, aumentando a eficiência do acesso à memória.

O Que é Padding?

Padding é o espaço adicional, ou bytes, que o compilador insere entre campos de uma struct para garantir que os campos estejam corretamente alinhados. Esses bytes não armazenam informações úteis, mas são necessários para atingir o alinhamento correto.

Considere a struct abaixo:

type StructA struct {
    A int32
    B int64
    C int32
}

Neste caso, o compilador insere 4 bytes de padding entre A e B para que B comece em um endereço alinhado de 8 bytes, atendendo seu requisito de alinhamento. Sem o uso apropriado de padding, o processador poderá precisar mais de um ciclo de memória para operar nos dados, prejudicando a eficiência.

Como Otimizar o Uso de Memória?

A melhor prática é organizar os campos da struct do tipo maior para o menor, agrupando tipos semelhantes. Isso ajuda a minimizar o padding necessário, resultando em uma struct mais compacta e eficiente.

Exemplo de Struct Ineficiente:

type StructA struct {
    A int32
    B int64
    C int32
}

Exemplo de Struct Otimizada:

type StructB struct {
    B int64 // maior tipo primeiro (8 bytes)
    A int32 // seguido pelos menores (4 bytes)
    C int32 // agrupado com A
}

Ao reorganizar os campos como visto em StructB, evitamos o preenchimento desnecessário, resultando em uma estrutura mais eficiente em termos de memória.

Ferramentas para Auxiliar na Otimização

Para analisar e otimizar automaticamente a disposição dos campos em structs, você pode usar ferramentas como fieldalignment. Essa é uma ferramenta nativa da plataforma do Go. Para instalar a última versão é só usar o comando:

go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest

Essa ferramenta tem duas funções principais, a primeira é apenas te dar um feedback do que pode ser alterado passando o comando “fieldalignment ./…” dentro da sua aplicação. E a segunda (e a minha favorita) é o ajuste “automágico” das structs com a flag “-fix”.
Um exemplo simples:

Exemplo de Saída do fieldalignment:

Esta saída mostra as alterações na struct adequando para o melhor uso de memória.

Conclusão

Alinhar as structs de forma estratégica é mais do que um mero ajuste de estilo: é um passo essencial para garantir que seu código Go seja mais eficiente e performático. Em sistemas complexos, qualquer economia de memória ou melhora na performance pode ter um impacto significativo. Portanto, reserve um tempo para revisar e otimizar suas structs utilizando ferramentas automatizadas, assegurando o máximo desempenho para sua aplicação. 🚀

Dica de Otimização em Go: A Ordem dos Campos em Structs Importa! was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O Golang é provavelmente uma das linguagens de programação que mais cresce em adoção em grandes empresas devido ao seu grande suporte de comunidade e ferramental que torna o dia a dia com a linguagem fácil de manter e escalar.

Neste cenário onde grandes empresas estão incluindo o Golang em suas linguagens preferidas para novos times e projetos, cresce a necessidade de adoção a capacidade de observabilidade aos grandes pacotes da comunidade para que permita acompanhar de forma mais detalhada como nossa aplicação interage com esses pacotes.

Como usar o OpenTelemetry no Golang

Para esse exemplo vou utilizar o Gin que é um famoso pacote que nos ajuda na construção de API’s flexíveis e com ótimo suporte de comunidade, e vamos precisar dos seguintes itens instalados em nossa máquina para funcionar corretamente:

• Docker
• Go 1.23

Dito isso vamos iniciar o nosso projeto com o go mod init e nomear nosso projeto da forma que fizer sentindo, e após isto, instalar os seguintes pacotes abaixo:

go get go.opentelemetry.io/otel \
    go.opentelemetry.io/otel/trace \
    go.opentelemetry.io/otel/sdk \
    go.opentelemetry.io/otel/sdk/resource \
    go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

Após instalado os pacotes vamos iniciar a implementação do nosso Provider, nesse meu exemplo vou usar como base uma aplicação que esteja utilizando o gin como servidor http ao qual preciso instrumentar as requisições, iniciamos com a configuração do TraceProvider dentro de um arquivo chamado main.go iniciando com o bloco de código abaixo:

package main

import (
 "context"

 "go.opentelemetry.io/otel"
 "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
 "go.opentelemetry.io/otel/propagation"
 "go.opentelemetry.io/otel/sdk/resource"
 sdktrace "go.opentelemetry.io/otel/sdk/trace"
 semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)

func setupOpenTelemetry(environment string, serviceName string) (*sdktrace.TracerProvider, error) {
 var tp *sdktrace.TracerProvider
 var err error
 ctx := context.Background()

 tp, err = setupProvider(ctx, environment, serviceName)
 if err != nil {
  return nil, err
 }
 otel.SetTracerProvider(tp)
 otel.SetTextMapPropagator(
  propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}),
 )

 return tp, nil
}

func setupProvider(ctx context.Context, environment string, serviceName string) (*sdktrace.TracerProvider, error) {
 res, err := resource.New(ctx,
  resource.WithFromEnv(),
  resource.WithAttributes(
   semconv.ServiceNameKey.String(serviceName),
  ),
 )

 if err != nil {
  return nil, err
 }

 var traceExporter sdktrace.SpanExporter

 // Configuração do Exporter em gRPC, que é um requisito padrão em nossa arquitetura com OpenTelemetry
 traceExporter, err = otlptracegrpc.New(ctx)
 if err != nil {
  return nil, err
 }

 bsp := sdktrace.NewBatchSpanProcessor(traceExporter)

 tp := sdktrace.NewTracerProvider(
  // Configuração do SampleRate via ParentBasedTraceIDRatio
  sdktrace.WithSampler(sdktrace.AlwaysSample()),
  sdktrace.WithResource(res),
  sdktrace.WithSpanProcessor(bsp),
  sdktrace.WithResource(resource.NewWithAttributes(
   semconv.SchemaURL,
   semconv.ServiceNameKey.String(serviceName),
   semconv.DeploymentEnvironmentKey.String(environment),
  )),
 )

 return tp, nil
}

Integrando o OpenTelemetry ao Gin

Após a criação das funções de configuração do OpenTelemetry, o que vai faltar é a configuração do server que vamos integrar o nosso OpenTelemetry, abaixo tenho uma demonstração utilizando o Gin de como podemos fazer integrar facilmente em nosso framework ou pacote, onde primeiro vamos precisar instalar os pacotes e depois implementar nosso código:

go get github.com/gin-gonic/gin \
 go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin

Após instalarmos os pacotes necessários podemos seguir com a implementação:

import (
 "context"
 "log"

 "github.com/gin-gonic/gin"
 "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
)

func main() {
 // Inicializamos o TracerProvider para que possamos integrar ao nosso GracefulShutdown
 tp, err := setupOpenTelemetry("local", "go-otel-basic")

 if err != nil {
  log.Fatal(err)
 }

 defer func() {
  if err := tp.Shutdown(context.Background()); err != nil {
   log.Printf("Error shutting down tracer provider: %v", err)
  }
 }()

 r := gin.New()
 // Injetamos o Middleware que vai fazer a instrumentação dos nossos requests
 r.Use(otelgin.Middleware("http-server"))

 r.GET("/up", func(c *gin.Context) {
  c.JSON(200, gin.H{
   "hello": "world",
  })
 })

 r.Run()
}

....

Para que possamos testar essa aplicação vamos precisar configurar localmente um Collector do OpenTelemetry, onde temos várias alternativas como o Jaeger, SigNoz, Grafana Tempo, etc. Mas para simplificar nossa implementação local vamos seguir com o Jaeger configurado via docker compose, onde vamos precisar criar um arquivo com o nome compose.yml e adicionar o conteúdo conforme demonstrado abaixo:

services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "16686:16686"
      - "4317:4317"

Após criação do arquivo do Docker Compose, conseguimos executar nosso pequeno projeto com o seguinte comando abaixo:

docker compose up -d

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 go run main.go

# Chamada para a API criada
curl --location '<http://localhost:8080/up>'

Pronto, agora você pode acessar o http://localhost:16686 onde vai poder visualizar o Trace gerado pela a requisição realizou para o serviço que subiu, neste link você tem acesso ao código final da implementação, e na imagem abaixo um exemplo de como o Jaeger vai mostrar o Trace:

Próximos passos

Se você chegou aqui e realizou todos os passos que descrevi em uma aplicação existente deve estar se perguntando agora “mas x integração minha não instrumentou”, bom neste caso a integração da instrumentação para o banco de dados, client http, e quaisquer outra ferramenta vai precisar integrar manualmente com a sua ferramenta ou buscar uma integração oficial como é o caso dessas abaixo:

• database/sql
• mongo-driver
• grpc
• net/http (client, server)

Como pode ver cada biblioteca vai possuir uma integração da comunidade, ou caso a mesma não possua, você pode realizar essa instrumentação de forma manual, o que te garante certa praticidade. É isso se tiverem dúvidas quanto a essas implementações ou como podemos evoluir ela ainda mais, comentem que eu posso fazer algo mais especifico ou complexo para mostrar de exemplo.

Tracing no Golang com o OpenTelemetry was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Nos últimos meses este seja o principal item no qual tenho trabalhado lá na Fretebras, como podemos melhorar nossas ferramentas de observabilidade tanto com material para que os times possam integrar de forma mais prática a telemetria, quanto com alternativas quando a aplicação legada não tem suporte as principais bibliotecas disponíveis no mercado. Hoje o foco dessa postagem é o PHP com OpenTelemetry, que é a principal linguagem da empresa ainda hoje, mesmo que ela não seja mais a linguagem da moda, alinhada com um bom framework (Laravel) e uma comunidade extremamente ativa é um canivete suíço quando se trata de velocidade de entrega.

Como usar no PHP?

Há mais de uma forma de utilizar o OpenTelemetry (Otel) no PHP, mas pelas experiências e testes que fiz essa ainda é a melhor opção que temos para utilizar o Otel dentro do ecossistema do PHP, que seria através da extensão do opentelemetry a qual pode ser instalada via pecl no servidor ou container que você esteja utilizando, abaixo mostro como pode ser feito

# Instala a extensão via pecl
pecl install opentelemetry

## Quando estiver utilizando via a imagem Docker do PHP, é necessário ativar a extensão após sua instalação
docker-ext-enable opentelemetry

# Para verificar que o mesmo foi instalado
php -m | grep opentelemetry

Após a instalação e ativação da extensão podemos fazer o próximo passo que é a instalação dos pacotes via composer. Nesta forma de integração vamos utilizar os pacotes mantidos pelo core team do Otel, o qual irá nós poupar bastante trabalho se fossemos realizar a integração manual. Para que possamos identificar o pacote que melhor se adeque a nossa necessidade, é necessário verificar alguns itens antes da instalação, sendo eles como:

• Qual banco de dados utilizamos?
• Aplicamos alguma das seguintes PSR (PSR-3, PSR-15, PSR-14, PSR-15)
• Qual método de exportação vamos utilizar, gRPC ou HTTP? Zipkin ou OTLP?

Com essas perguntas respondidas será possível definir a instalação de alguns pacotes como o open-telemetry/opentelemetry-auto-psr15 em que conseguimos instrumentar automaticamente toda implementação da PSR-15, outra muito importante é a open-telemetry/opentelemetry-auto-pdo onde temos a instrumentação das implementações do PDO (PHP Data Objects) de forma automática sem a necessidade de customizações para o seu funcionamento, e por fim, uma outra integração bastante relevante é a com o Exporter que desejamos usar para enviar as informações para o nosso Collector neste caso, se não utilizar o gRPC, acredito que a melhor seja open-telemetry/exporter-otlp que é bastante agnóstica ao serviço de Collector que utilizarmos. Abaixo o comando para realizar a instalação:

composer require open-telemetry/opentelemetry-auto-psr15 \\
	open-telemetry/opentelemetry-auto-pdo \\
	open-telemetry/exporter-otlp \\
	open-telemetry/gen-otlp-protobuf

Para o funcionamento real da extensão e dos pacotes instalados é necessário configurarmos as variáveis de ambiente que são utilizadas pela extensão e seus pacotes para identificar como enviar as informações, abaixo um exemplo das variáveis de ambiente:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_PROPAGATORS=baggage,tracecontext

E quando tenho um framework?

A instalação anterior tratava principalmente casos onde não temos nenhum Framework instalado em nossos projetos, o que não é algo muito recomendado atualmente tendo em vista a velocidade que uma comunidade de pessoas consegue tratar uma CVE (Common Vulnerabilities and Exposures) que possa atingir um grande framework como Laravel ou Symfony.

Como na Fretebras trabalhamos com Laravel, vou exemplificar como podemos fazer a instalação dos pacotes necessários para integrar ele de forma automática. Assim como os outros pacotes que mostrei antes é bastante simples, só é necessária a instalação de um pacote open-telemetry/opentelemetry-auto-laravel, neste pacote há bem mais ferramentas do que em outros pacotes que exemplifiquei por estarmos trabalhando em um framework.

composer require open-telemetry/opentelemetry-auto-laravel

Esse pacote inclui até o momento a instrumentação automática dos seguintes itens nativos do Laravel: Requests, Console/Command, Queue, Cache, ClientRequest, Exceptions, Log e as Queries, ufa acredito que seja quase tudo até o momento, mas, como um framework que está sempre se desenvolvendo pode ser que alguma funcionalidade muito nova ainda não tenha sua própria implementação dentro do pacote oficial, contudo, como o Otel é bastante flexível, ainda é possível fazer uma integração manual do seu pacote preferido.

Alguns pacotes famosos como mongodb/laravel-mongodb não funcionam automaticamente e necessitam de uma integração manual ou o uso do pacote open-telemetry/opentelemetry-auto-mongodb se quiser uma integração que não seja tão presa ao Laravel, mas ainda sim conseguir capturar as interações com o MongoDB sem maiores problemas.

Complementando seu conhecimento

Essa postagem foi mais para falar de uma forma mais ampla como podemos fazer para utilizar o OpenTelemetry no PHP, e consequentemente no framework mais famoso dele, o Laravel, entretanto isso é apenas uma pequena ponta de um grande Iceberg que é a Observabilidade no geral, quanto em aplicações PHP em que podemos ir para casos onde nossa aplicação gera métricas de uso e disponibilidade em tempo real utilizando o OpenTelemetry como agregador desses dados.

Como todo estudo ele nos gera diversas referências que estou listando aqui abaixo para complementar o conhecimento de quem leu até aqui:

• O guia oficial do OpenTelemetry para o PHP
• Uma postagem de instrumentação manual no Laravel (com ótimos exemplos de como podemos fazer isso manualmente)
• Pacote experimental da Spatie para o Laravel
• E um ótimo pacote da KeepSuite que re-implementa de maneira mais customizável o pacote oficial da Otel

A Observabilidade no PHP com OpenTelemetry was originally published in Frete.com Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.