mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-08-13 01:38:41 +00:00
7642e615a3
Some checks failed
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Check Documentation Broken Links / Check broken links (push) Has been cancelled
Vulnerability Scan / Detect changes (push) Has been cancelled
Vulnerability Scan / pip-audit (push) Has been cancelled
Nightly Canary Release / Check for new commits (push) Has been cancelled
Nightly Canary Release / Build nightly packages (push) Has been cancelled
Nightly Canary Release / Publish nightly to PyPI (push) Has been cancelled
* feat(flow): report flow outcome and human-in-the-loop signals A flow reported only that it started. FlowFinishedEvent, FlowFailedEvent, MethodExecutionFailedEvent, MethodExecutionPausedEvent and FlowPausedEvent all reached the console formatter and stopped there, and FlowInputRequestedEvent, FlowInputReceivedEvent and ConversationTurnFailedEvent had no listener at all - so success rate, failure rate and every HITL pause were unmeasurable. Adds flow:completed, flow:failed, flow:method_failed, flow:paused, flow:hitl_paused, flow:input_requested, flow:input_received and flow:conversation_turn_failed as feature-usage spans, which the existing feature-usage aggregation already reads. Deliberately does not hold the Flow Execution span open to measure duration: flow_executions_daily_target counts those spans at start, so a run that never finishes would disappear from the count entirely. Duration needs its own span. Counts only - flow names, method names, error text and flow state are never recorded. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * feat(flow): record how long a flow ran Adds a Flow Completed span carrying flow_name, duration_ms and outcome, emitted when a flow finishes or fails. Elapsed time comes from a monotonic stamp taken at flow start and cleared on use. Kept separate from the Flow Execution span rather than holding that one open: it is emitted and closed at start and the daily aggregate counts it, so holding it would drop every run that is killed or crashes from the execution count. A killed run now simply has no Flow Completed row, and the count is unaffected. Elapsed time is an explicit duration_ms attribute rather than the span's own duration, which the ingestion pipeline stores as a suffixed string ("0.0000184s") that downstream aggregation parses to zero. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * feat(flow): tag flow origin and report resumed runs Two gaps found while testing the pause/resume path end to end. Resumed runs were invisible. There is no resume event: a restored run re-enters through kickoff(), so it looked identical to a fresh start. flow:resumed is derived from _is_execution_resuming at flow start, which makes flow:paused - flow:resumed the abandonment rate. Flow counts are dominated by CrewAI's own AgentExecutor, which is itself a Flow and runs once per agent execution - it is the top flow in the warehouse by a wide margin. Nothing distinguished it from a user's flows except guessing at the name. Both Flow Execution and Flow Completed now carry origin: "internal" when the flow class is defined under crewai.*, "user" otherwise. Tagging only the new span would have left the existing daily count unsplittable. Both span methods take origin with a default, so their signatures stay backward compatible. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * fix(flow): scope outcome and resume signals to user flows Two findings from review, both confirmed against the code. Outcome features counted CrewAI's own flows. The agent executor, memory encoding and memory recall are all Flows and all set suppress_flow_events; they run far more often than anything a user wrote, so flow:completed, flow:failed and flow:method_failed were mostly bookkeeping. Those three are now emitted only for flows the caller wrote. Internal outcomes are still recorded on the Flow Completed span, which carries origin. flow:resumed counted checkpoint restores. _is_execution_resuming is set both by from_pending (a human pause) and by a checkpoint restore that never paused for anyone, so resumes could exceed pauses and the abandonment rate was unusable. Keyed off _pending_feedback_context instead, which only from_pending sets. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * fix(flow): declare internal flows instead of inferring them Three findings from review, all confirmed against the code. Gating on suppress_flow_events was wrong. That flag asks for console quiet and is a public field, so a caller who set it on their own flow silently lost flow:completed, flow:failed and flow:method_failed. Deciding origin from the defining module was also wrong. Flow.from_declaration() returns a Flow typed in crewai.flow.flow, so a caller's declarative flow was reported as one of CrewAI's own - the inversion this split exists to prevent. Both had the same root cause: the discriminator was inferred. Flow now declares is_crewai_internal, set on the agent executor and the memory encoding/recall flows, and one helper serves both origin and the outcome gate. A failed conversational session was reported as completed. Its session closes with FlowFinishedEvent whatever happened, so a failed turn produced flow:conversation_turn_failed and flow:completed together. The turn failure is now recorded on the flow and read back when the session finishes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * refactor(flow): report flow lifecycle as spans, not feature usage Flow start, completion, pause and method failure are lifecycle facts, and the lifecycle is reported as spans everywhere else. Reporting them through feature usage put them in a table that aggregates on the feature string alone - it cannot carry origin, duration or outcome, so those signals could never be split between a user's flows and the ones CrewAI runs for itself. Adds Flow Paused and Flow Method Failed spans, and a resumed marker on Flow Execution so a run restored from a pause is not counted as a second fresh start. Removes the duplicate feature rows for completed, failed, method_failed, paused and resumed - every one of those facts is now on a span, with more attached to it than the feature row ever carried. Feature usage keeps only genuine adoption signals: flow:hitl_paused, flow:input_requested, flow:input_received and flow:conversation_turn_failed. Also clears the conversational turn-failure flag on every terminal path. A turn that failed without deferred finalization ends via FlowFailedEvent, and the flag left set there marked the next run on that instance as failed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * test(flow): update the flow_execution_span caller for the resumed argument Adding the resumed marker changed a signature that tests/utilities/test_events.py asserts on exactly, and that assertion was not re-run before pushing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * test(flow): make the checkpoint-restore guard actually guard The test asserted that flow:resumed was absent from feature usage, but that signal moved onto the Flow Execution span. The assertion could no longer fail, so a regression that mis-tagged checkpoint restores as resumes would have gone unnoticed. Now asserts the resumed attribute, and waits for the handlers: the manual emit dispatches asynchronously, so the previous shape also read its result before the listener had run. Confirmed it discriminates - keying resumed off _is_execution_resuming again fails it with [('RestoredFlow', True)] == [('RestoredFlow', False)]. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH * fix(telemetry): record the resumed marker as a string Verified end to end against the live collector and ClickHouse: the pipeline encodes a boolean attribute as the presence of a vBool key, so false arrives as the key simply being absent. That is invisible in the schema and easy to read wrongly - crew_memory is extracted as "the attribute exists" and consequently reports 1 for 99.8% of crews against a field that defaults to False. A string leaves nothing to infer. Confirmed in the warehouse: the emitted span reads resumed = "false". Adds direct coverage for the attributes each flow span records, including both resumed values, and resets the Telemetry singleton in the helper so more than one span method can be exercised per session. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
84 lines
8.6 KiB
Plaintext
84 lines
8.6 KiB
Plaintext
---
|
|
title: Telemetria
|
|
description: Entendendo os dados de telemetria coletados pelo CrewAI e como eles contribuem para o aprimoramento da biblioteca.
|
|
icon: signal-stream
|
|
mode: "wide"
|
|
---
|
|
|
|
## Telemetria
|
|
|
|
<Note>
|
|
Por padrão, não coletamos dados que possam ser considerados informações pessoais segundo a GDPR e outras regulamentações de privacidade.
|
|
Coletamos nomes das ferramentas e funções dos agentes, portanto, evite incluir qualquer informação pessoal nos nomes das ferramentas ou nas funções dos agentes.
|
|
Como nenhuma informação pessoal é coletada, não é necessário se preocupar com localidade dos dados.
|
|
Quando `share_crew` está ativado, dados adicionais são coletados e podem conter informações pessoais caso sejam incluídas pelo usuário.
|
|
Usuários devem tomar cuidado ao habilitar este recurso para garantir conformidade com regulamentações de privacidade.
|
|
</Note>
|
|
|
|
O CrewAI utiliza telemetria anônima para coletar estatísticas de uso com o objetivo principal de aprimorar a biblioteca.
|
|
Nosso foco está em melhorar e desenvolver as funcionalidades, integrações e ferramentas mais utilizadas pelos usuários.
|
|
|
|
É fundamental compreender que, por padrão, **NENHUM dado pessoal é coletado** referente a prompts, descrições de tarefas, histórias ou objetivos dos agentes,
|
|
uso de ferramentas, chamadas de API, respostas, quaisquer dados processados pelos agentes ou segredos e variáveis de ambiente.
|
|
Quando o recurso `share_crew` está ativado, dados detalhados, incluindo descrições das tarefas, histórias ou objetivos dos agentes e outros atributos específicos são coletados
|
|
para fornecer insights mais detalhados. Essa coleta expandida pode incluir informações pessoais caso o usuário as tenha inserido em seus crews ou tarefas.
|
|
Usuários devem considerar cuidadosamente o conteúdo de seus crews e tarefas antes de habilitar o `share_crew`.
|
|
A telemetria pode ser desabilitada ao definir a variável de ambiente `CREWAI_DISABLE_TELEMETRY` como `true` ou ao definir `OTEL_SDK_DISABLED` como `true` (observe que esta última desabilita toda instrumentação OpenTelemetry globalmente).
|
|
|
|
### Exemplos:
|
|
```python
|
|
# Desabilitar apenas a telemetria do CrewAI
|
|
os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
|
|
|
|
# Desabilitar todo o OpenTelemetry (incluindo CrewAI)
|
|
os.environ['OTEL_SDK_DISABLED'] = 'true'
|
|
```
|
|
|
|
### Isolamento da sua própria configuração do OpenTelemetry
|
|
|
|
A telemetria do CrewAI roda em seu próprio `TracerProvider` privado e nunca se
|
|
registra como o provider global. Isso mantém as duas direções separadas:
|
|
|
|
- Spans de outras bibliotecas instrumentadas no seu processo — frameworks web,
|
|
clientes de banco de dados, clientes HTTP — nunca são enviados ao CrewAI.
|
|
- Os spans de telemetria do CrewAI nunca são enviados ao seu backend de
|
|
observabilidade, portanto não aparecerão no Langfuse, Braintrust, Phoenix ou
|
|
em qualquer outro coletor que você configurar.
|
|
|
|
As integrações de observabilidade não são afetadas: elas instrumentam o CrewAI
|
|
por meio do próprio tracer provider, que é independente do descrito aqui.
|
|
|
|
### Explicação dos Dados:
|
|
| Padrão | Dados | Razão e Especificidades |
|
|
|--------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| Sim | Versão do CrewAI e Python | Rastreia versões dos softwares. Exemplo: CrewAI v1.2.3, Python 3.8.10. Sem dados pessoais. |
|
|
| Sim | Metadados do Crew | Inclui: chave e ID gerados aleatoriamente, tipo de processo (ex: 'sequential', 'parallel'), flag booleana para uso de memória (true/false), quantidade de tarefas, quantidade de agentes. Tudo não pessoal. |
|
|
| Sim | Dados do Agente | Inclui: chave e ID gerados aleatoriamente, nome da função (não deve incluir info pessoal), configurações booleanas (verbose, delegação habilitada, execução de código permitida), máximo de iterações, máximo de RPM, limite de tentativas, info do LLM (ver Atributos LLM), lista de nomes de ferramentas (não deve conter info pessoal). Sem dados pessoais. |
|
|
| Sim | Metadados da Tarefa | Inclui: chave e ID gerados aleatoriamente, configurações de execução booleanas (async_execution, human_input), função e chave do agente associado, lista de nomes de ferramentas. Tudo não pessoal. |
|
|
| Sim | Estatísticas de Uso de Ferramentas | Inclui: nome da ferramenta (não deve incluir info pessoal), número de tentativas de uso (inteiro), atributos LLM utilizados. Sem dados pessoais. |
|
|
| Sim | Dados de Execução de Testes | Inclui: chave e ID aleatórias do crew, número de iterações, nome do modelo usado, score de qualidade (float), tempo de execução (em segundos). Tudo não pessoal. |
|
|
| Sim | Dados do Ciclo de Vida da Tarefa | Inclui: horários de criação, início/fim de execução, identificadores de crew e tarefa. Armazenado como spans com timestamps. Sem dados pessoais. |
|
|
| Sim | Atributos do LLM | Inclui: nome, model_name, model, top_k, temperatura e nome da classe do LLM. Todos técnicos, sem dados pessoais. |
|
|
| Sim | Tentativa de Deploy do Crew pelo CLI do crewAI | Inclui: O fato de um deploy estar sendo realizado e o crew id, e se está tentando buscar logs, sem mais dados. |
|
|
| Sim | Ambiente de Execução | Inclui: qual assistente de código com IA está executando o processo, se houver (um de uma lista fixa como `claude_code`, `codex`, `cursor` ou `unknown`), onde o processo é executado (um de uma lista fixa como `ci`, `container`, `serverless`, `interactive`) e o `project_id` do seu `pyproject.toml` quando houver um configurado. A detecção lê apenas se variáveis de ambiente conhecidas estão definidas, nunca seus valores. Sem dados pessoais. |
|
|
| Sim | Sinais de Ciclo de Vida do Flow | Inclui: que um flow iniciou, se foi concluído ou falhou, se um de seus métodos falhou, se pausou para entrada ou feedback humano, se o início foi uma execução retomada, se um turno de conversa falhou, por quanto tempo o flow executou e se o flow é um que o CrewAI executa internamente ou um que você escreveu. O nome do flow é registrado, como já ocorre na criação e execução do flow. Nomes de métodos, mensagens de erro e estado do flow nunca são registrados. Sem dados pessoais. |
|
|
| Não | Dados Expandidos do Agente | Inclui: descrição do objetivo, texto da história, identificador de arquivo i18n prompt. Usuários devem garantir que não haja info pessoal nesses campos de texto. |
|
|
| Não | Informações Detalhadas da Tarefa | Inclui: descrição da tarefa, descrição do resultado esperado, referências de contexto. Usuários devem garantir que não haja info pessoal nessas áreas. |
|
|
| Não | Informações de Ambiente | Inclui: plataforma, release, sistema, versão e quantidade de CPUs. Exemplo: 'Windows 10', 'x86_64'. Sem dados pessoais. |
|
|
| Não | Entradas e Saídas de Crew e Tarefas | Inclui: parâmetros de entrada e resultados como dados não identificáveis. Usuários devem garantir que não haja info pessoal. |
|
|
| Não | Dados Abrangentes de Execução do Crew | Inclui: logs detalhados das operações do crew, dados de todos os agentes e tarefas, resultado final. Tudo de natureza técnica, sem dados pessoais. |
|
|
|
|
<Note>
|
|
"Não" na coluna "Padrão" indica que esse dado só é coletado quando `share_crew` está configurado como `true`.
|
|
</Note>
|
|
|
|
### Compartilhamento Avançado de Telemetria (Opt-In)
|
|
|
|
Usuários podem optar por compartilhar toda a telemetria habilitando o atributo `share_crew` como `True` nas configurações do seu crew.
|
|
Ao habilitar `share_crew`, há coleta detalhada dos dados de execução do crew e das tarefas, incluindo `goal`, `backstory`, `context` e `output` das tarefas.
|
|
Isso permite uma compreensão mais profunda dos padrões de uso.
|
|
|
|
<Warning>
|
|
Se você habilitar o `share_crew`, os dados coletados podem incluir informações pessoais caso estas estejam presentes nas configurações do crew, descrições de tarefas ou outputs.
|
|
Os usuários devem revisar cuidadosamente seus dados e garantir conformidade com a GDPR e outras regulamentações de privacidade antes de habilitar esse recurso.
|
|
</Warning> |