mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-21 02:16:27 +00:00
9e9a8577be
* feat(telemetry): report project creation with the id minted for it Acquisition was only observable from a project's first run. That misses every project created and never run, and dates the rest to the wrong day. All three scaffolding paths already mint a project_id into the new pyproject.toml. None of them reported it, and two of them - create_crew and create_json_crew, which is the default `crewai create crew` path - emitted no telemetry at all. `Project Created` carries the kind (crew, json_crew, flow) and the id that was just minted, and is emitted after the mint so it can carry it. The attribute is `created_project_id`, not `project_id`, because those are two different things. CommonAttributesSpanProcessor stamps `project_id` on every span from get_project_id(), which reads the current working directory and is cached for the life of the process - during `crewai create` that describes the directory the command was run from, not the project being created. Reusing the name would have given one column two meanings depending on span type. Nothing is emitted for `create_crew(parent_folder=...)`: that adds a crew to a project which already exists, mints no id, and is not an acquisition. The existing `Flow Creation` span is left exactly as it is. Note for whoever reads it: it is emitted from two places with two different meanings - CLI scaffolding (create_flow.py) and runtime flow construction (event_listener.py on FlowCreatedEvent) - so it cannot separate acquisition from usage. Not changed here because it is a live series and renaming it would break continuity. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * test(telemetry): stop the creation-span tests exporting to the real collector The recorded_spans fixture has to enable telemetry for its assertions to mean anything - a disabled Telemetry never builds self.provider, so every assertion would pass vacuously against a non-recording span. But enabling it is exactly what makes __init__ wire a BatchSpanProcessor around the real SafeOTLPSpanExporter, pointed at the production collector. Measured, with a spy on both SafeOTLPSpanExporter classes reporting at interpreter exit: before this change the file made 3 real export calls, handed 3 synthetic Project Created spans with invented created_project_id values to the production exporter, and completed 3 connects to the collector. After: 0, 0, 0. Sampling at pytest_sessionfinish reports 0 either way and is how this was missed - BatchSpanProcessor flushes on a background timer, and with no provider.shutdown() the flush lands in the atexit handler, which runs after sessionfinish. --block-network does not prevent it: it is function-scoped and only swaps socket.connect, which a background batch thread outlives. Follows telemetry_with_exporter in tests/telemetry/test_tracer_isolation.py: _NullExporter swapped in before construction, _register_shutdown_handlers suppressed so no atexit hook is left behind, and provider.shutdown() in finally. Patch target is crewai_core because that is where this Telemetry comes from. Also disambiguates the docs rows: the minted ID belongs to the new project, not to the directory the command ran in, and the two can differ. Reworded in all four languages rather than renaming the token to created_project_id - this table documents data, never span-attribute keys (kind and crewai_version on the same row are unnamed), and `project_id` is already the page's name for the pyproject.toml key. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * docs(ar): use tanwin fath on the letter, not on the alif مشروعًا / جديدًا rather than مشروعاً / جديداً, in the row added by this PR. Both forms appear in docs/edge/ar (3 each), so this is not a house convention being broken either way; the corrected form is the more standard one and the text is mine. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * docs: stop the creation row implying the span's project_id holds the minted value CodeRabbit re-raised this as Major after I rejected the first version, and it was right to. My rejection argued the page never names wire keys, so introducing created_project_id would be its only one. That part still holds -- grep finds no attribute key anywhere in the four files. But it was the wrong conclusion: the row still used the token `project_id` for a value the span does NOT carry under that key, while the same span's real project_id holds the cwd-derived value. The row also already exposes literal wire values (`crew`, `json_crew`, `flow` are the actual kind values), so "this page has no wire detail" was overstated. Dropping the token resolves the ambiguity without adding the page's only key name: the row now says "the project ID minted for that new project", and names `project_id` only to say the minted value is recorded separately from it. All four languages. No docs/v*/ touched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * docs: use an em dash in the creation row, matching the rest of the page The two ASCII `--` occurrences in these files were both mine, introduced by this PR: the page otherwise uses em dashes throughout (en 4, ar 4, ko 2, pt-BR 4). CodeRabbit flagged pt-BR; the same slip was in en, so both are fixed. Now zero ASCII `--` across all four language files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Vidit Ostwal <110953813+Vidit-Ostwal@users.noreply.github.com>
84 lines
11 KiB
Plaintext
84 lines
11 KiB
Plaintext
---
|
|
title: 텔레메트리
|
|
description: CrewAI에서 수집되는 텔레메트리 데이터와 이 데이터가 라이브러리의 향상에 어떻게 기여하는지 이해합니다.
|
|
icon: signal-stream
|
|
mode: "wide"
|
|
---
|
|
|
|
## 텔레메트리
|
|
|
|
<Note>
|
|
기본적으로, 저희는 GDPR 및 기타 개인정보 보호 규정하에서 개인정보로 간주되는 어떠한 데이터도 수집하지 않습니다.
|
|
도구 이름과 에이전트 역할만을 수집하므로, 도구 이름이나 에이전트 역할에 개인정보를 포함하지 않도록 주의하시기 바랍니다.
|
|
개인정보가 수집되지 않으므로 데이터 거주지에 대해 걱정할 필요가 없습니다.
|
|
`share_crew`가 활성화되면, 사용자가 포함한 경우 개인정보를 포함할 수 있는 추가 데이터가 수집될 수 있습니다.
|
|
사용자는 이 기능을 활성화할 때 개인정보 보호 규정 준수를 위해 주의를 기울여야 합니다.
|
|
</Note>
|
|
|
|
CrewAI는 익명 텔레메트리를 활용하여 사용 통계를 수집하며, 주요 목적은 라이브러리의 향상에 있습니다.
|
|
저희의 초점은 사용자들이 가장 많이 사용하는 기능, 통합, 도구를 개선하고 개발하는 데 있습니다.
|
|
|
|
기본적으로 프롬프트, 작업 설명, 에이전트의 배경 이야기나 목표, 도구 사용, API 호출, 응답, 에이전트가 처리하는 데이터, 또는 시크릿과 환경 변수 등과 관련된 **개인 데이터는 절대 수집하지 않습니다**.
|
|
`share_crew` 기능이 활성화되면, 보다 심층적인 통찰을 제공하기 위해 작업 설명, 에이전트의 배경 이야기나 목표, 기타 특정 속성 등 상세한 데이터가 수집됩니다.
|
|
이 확대된 데이터 수집에는 사용자가 crew나 작업에 개인정보를 포함한 경우, 개인정보가 포함될 수 있습니다.
|
|
사용자는 `share_crew`를 활성화하기 전에 crew와 작업의 내용을 신중하게 검토해야 합니다.
|
|
사용자는 환경 변수 `CREWAI_DISABLE_TELEMETRY`를 `true`로 설정하거나, `OTEL_SDK_DISABLED`를 `true`로 설정하여 텔레메트리를 비활성화할 수 있습니다(후자의 경우 전체 OpenTelemetry 계측이 전역에서 비활성화된다는 점에 유의하십시오).
|
|
|
|
### 예시:
|
|
```python
|
|
# CrewAI telemetry만 비활성화
|
|
os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
|
|
|
|
# 모든 OpenTelemetry 비활성화(CrewAI 포함)
|
|
os.environ['OTEL_SDK_DISABLED'] = 'true'
|
|
```
|
|
|
|
### 사용자 OpenTelemetry 설정과의 격리
|
|
|
|
CrewAI의 telemetry는 자체 전용 `TracerProvider`에서 실행되며 자신을 전역
|
|
provider로 등록하지 않습니다. 이를 통해 양방향이 분리됩니다:
|
|
|
|
- 프로세스 내 다른 계측된 라이브러리(웹 프레임워크, 데이터베이스 클라이언트,
|
|
HTTP 클라이언트)의 span은 CrewAI로 전송되지 않습니다.
|
|
- CrewAI의 telemetry span은 사용자의 관측 가능성 백엔드로 전송되지 않으므로
|
|
Langfuse, Braintrust, Phoenix 또는 구성한 다른 수집기에 나타나지 않습니다.
|
|
|
|
관측 가능성 통합은 영향을 받지 않습니다: 해당 통합은 여기서 설명한 provider와
|
|
독립적인 자체 tracer provider를 통해 CrewAI를 계측합니다.
|
|
|
|
### 데이터 설명:
|
|
| 기본값 | 데이터 | 사유 및 세부 사항 |
|
|
|:--------|:-------------------------------------------|:----------------------------------------------------------------------------------------------------------------------|
|
|
| 예 | CrewAI 및 Python 버전 | 소프트웨어 버전을 추적합니다. 예: CrewAI v1.2.3, Python 3.8.10. 개인 정보 없음. |
|
|
| 예 | Crew 메타데이터 | 랜덤으로 생성된 키 및 ID, 프로세스 유형(예: 'sequential', 'parallel'), 메모리 사용 플래그(boolean, true/false), 실행에 입력이 전달되었는지를 나타내는 플래그(boolean, true/false — 입력 키나 값 자체는 포함되지 않으며, 이는 `share_crew`가 활성화된 경우에만 수집됩니다), 작업 수, 에이전트 수가 포함됩니다. 모두 비개인 정보입니다. |
|
|
| 예 | 에이전트 데이터 | 랜덤으로 생성된 키 및 ID, 역할 이름(개인 정보 포함 불가), boolean 설정(상세 출력, 위임 가능, 코드 실행 허용), 최대 반복 횟수, 최대 RPM, 최대 재시도 제한, LLM 정보(LLM 속성 참조), 도구 이름 목록(개인 정보 포함 불가) 포함. 개인 정보 없음. |
|
|
| 예 | 작업 메타데이터 | 랜덤으로 생성된 키 및 ID, boolean 실행 설정(async_execution, human_input), 관련 에이전트 역할 및 키, 도구 이름 목록이 포함됩니다. 모두 비개인 정보입니다. |
|
|
| 예 | 도구 사용 통계 | 도구 이름(개인 정보 포함 불가), 사용 시도 횟수(정수), 사용된 LLM 속성이 포함됩니다. 개인 정보 없음. |
|
|
| 예 | 테스트 실행 데이터 | crew의 랜덤 생성 키와 ID, 반복 횟수, 사용된 모델명, 품질 점수(실수), 실행 시간(초 단위)이 포함됩니다. 모두 비개인 정보입니다. |
|
|
| 예 | 작업 라이프사이클 데이터 | 생성 및 실행 시작/종료 시각, crew 및 작업 식별자가 포함됩니다. 타임스탬프를 포함한 span으로 저장됩니다. 개인 정보 없음. |
|
|
| 예 | LLM 속성 | LLM의 이름, model_name, 모델, top_k, temperature 및 클래스명이 포함됩니다. 모두 기술적이고 비개인 정보입니다. |
|
|
| 예 | crewAI CLI를 통한 프로젝트 생성 | 포함 항목: `crewai create`로 새 프로젝트가 생성되었다는 사실, 그 종류(`crew`, `json_crew` 또는 `flow`), 그리고 그 새 프로젝트에 발급되어 해당 프로젝트의 `pyproject.toml`에 기록된 프로젝트 ID. 이는 새 프로젝트 자체의 ID이며, 명령을 실행한 디렉터리의 `project_id`와는 별개로 기록됩니다 — 두 값은 다를 수 있습니다. 프로젝트 이름, 파일 내용, 코드는 기록되지 않습니다. 개인 정보 없음. |
|
|
| 예 | crewAI CLI를 통한 Crew 배포 시도 | 포함 항목: 배포가 시도되고 있다는 사실과 crew id, 로그를 가져오려고 하는지 여부, 그리고 배포가 CLI 명령에서 시작되었는지 실행 TUI에서 시작되었는지 여부. 프로젝트나 crew의 내용은 기록되지 않습니다. 개인 정보 없음. |
|
|
| 예 | 실행 환경 | 포함: 프로세스를 실행 중인 AI 코딩 어시스턴트(있는 경우, `claude_code`, `codex`, `cursor`, `unknown` 등 고정 목록 중 하나), 프로세스가 실행되는 위치(`ci`, `container`, `serverless`, `interactive` 등 고정 목록 중 하나), 그리고 `pyproject.toml`에 설정된 경우 `project_id`. 감지는 알려진 환경 변수의 설정 여부만 확인하며 값은 읽지 않음. 개인 데이터 없음. |
|
|
| 예 | Flow 라이프사이클 신호 | 포함 항목: flow의 시작, 완료 또는 실패 여부, 해당 메서드의 실패 여부, 사람의 입력이나 피드백을 위해 일시 중지되었는지 여부, 해당 시작이 재개된 실행이었는지 여부, 대화 턴의 실패 여부, flow 실행 시간, 그리고 해당 flow가 CrewAI가 내부적으로 실행하는 것인지 사용자가 작성한 것인지 여부. flow 이름은 flow 생성 및 실행에서와 마찬가지로 기록됩니다. flow 또는 해당 메서드가 실패하면 장애 진단을 위해 예외의 **클래스 이름**(예: `TimeoutError`)이 기록되며, 프롬프트·모델 출력·파일 경로·자격 증명이 포함될 수 있는 오류 메시지는 절대 기록되지 않습니다. 메서드 이름과 flow 상태는 절대 기록되지 않습니다. 개인 정보 없음. |
|
|
| 예 | 트레이스 공유 신호 | 포함 항목: 트레이스 배치가 CrewAI AMP에 성공적으로 공유되었는지 여부와, 익명으로(계정 생성 전) 공유되었는지 또는 계정에 연결되어 공유되었는지 여부. 모든 span과 마찬가지로 위에서 설명한 실행 환경 속성(구성된 경우 `project_id`, 코딩 어시스턴트, 런타임)도 함께 기록됩니다. 이 행은 공유 텔레메트리만 설명하며 — 트레이스 내용이나 공유된 트레이스 링크로 부여되는 접근 권한은 설명하지 않습니다. 트레이스 내용, 입력, 출력은 이 신호에는 기록되지 않습니다. 트레이스를 공유하기 전에 비밀 정보, 개인 데이터, AMP 편집 및 보존 설정을 검토하세요. |
|
|
| 아니오 | 에이전트 확장 데이터 | 목표 설명, 배경 이야기 텍스트, i18n 프롬프트 파일 식별자가 포함됩니다. 사용자들은 텍스트 필드에 개인 정보가 포함되지 않도록 해야 합니다. |
|
|
| 아니오 | 상세 작업 정보 | 작업 설명, 예상 출력 설명, 컨텍스트 참조가 포함됩니다. 사용자들은 이러한 필드에 개인 정보가 포함되지 않도록 해야 합니다. |
|
|
| 아니오 | 환경 정보 | 플랫폼, 릴리즈, 시스템, 버전, CPU 개수가 포함됩니다. 예: 'Windows 10', 'x86_64'. 개인 정보 없음. |
|
|
| 아니오 | crew 및 작업 입력 및 출력 | 비식별 데이터로서 입력 파라미터와 출력 결과가 포함됩니다. 사용자들은 개인 정보가 포함되지 않도록 해야 합니다. |
|
|
| 아니오 | 종합 crew 실행 데이터 | crew 작업, 모든 에이전트 및 작업 데이터, 최종 출력의 자세한 로그가 포함됩니다. 모두 비개인적이며 기술적인 성격입니다. |
|
|
|
|
<Note>
|
|
"기본값" 열의 "아니오"는 해당 데이터가 `share_crew`가 `true`로 설정된 경우에만 수집됨을 의미합니다.
|
|
</Note>
|
|
|
|
### 추가 텔레메트리 공유 선택
|
|
|
|
사용자는 crew 설정에서 `share_crew` 속성을 `True`로 설정하여 전체 텔레메트리 데이터를 공유하도록 선택할 수 있습니다.
|
|
`share_crew`를 활성화하면 `goal`, `backstory`, `context`, 그리고 task의 `output`을 포함한 crew 및 작업 실행에 대한 상세 데이터가 수집됩니다.
|
|
이를 통해 사용 패턴에 대한 더 깊은 인사이트를 얻을 수 있습니다.
|
|
|
|
<Warning>
|
|
`share_crew`를 활성화하면, crew 설정, task 설명, 또는 출력에 개인정보가 포함되어 있을 경우 이 정보가 수집될 수 있습니다.
|
|
사용자는 자신의 데이터를 신중하게 검토하고 이 기능을 활성화하기 전에 GDPR 및 기타 적용 가능한 개인정보 보호 규정을 준수하는지 확인해야 합니다.
|
|
</Warning> |