From 8f74482c9bb3307810aca9a9e8f4477a0b3d90d0 Mon Sep 17 00:00:00 2001 From: Vilson Rodrigues Date: Wed, 26 Nov 2025 12:31:15 -0300 Subject: [PATCH 1/3] chore: Improve repository structure with templates and documentation organization - Add CODEOWNERS for automatic review assignment - Add issue templates (bug report, feature request) - Add pull request template with comprehensive checklist - Add pre-commit config with gitleaks, uv-lock, and ruff - Improve release-drafter.yml with more categories and better organization - Move AUTOMATION.md and ROADMAP.md to docs/ directory - Remove MERGE_BOT_GUIDE.md (content moved to AUTOMATION.md in English) - Update AUTOMATION.md with /update command documentation - Move Development section from README to CONTRIBUTING.md - Update ROADMAP version from v0.2.0 to v1.1.0 - Update all documentation references to new file locations --- .github/CODEOWNERS | 22 ++ .github/ISSUE_TEMPLATE/bug_report.yml | 91 ++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 61 ++++++ .github/pull_request_template.md | 54 +++++ .github/release-drafter.yml | 31 ++- .pre-commit-config.yaml | 22 ++ CONTRIBUTING.md | 63 ++++++ MERGE_BOT_GUIDE.md | 234 --------------------- README.md | 57 +---- AUTOMATION.md => docs/AUTOMATION.md | 121 ++++++++++- ROADMAP.md => docs/ROADMAP.md | 2 +- 11 files changed, 463 insertions(+), 295 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .pre-commit-config.yaml delete mode 100644 MERGE_BOT_GUIDE.md rename AUTOMATION.md => docs/AUTOMATION.md (68%) rename ROADMAP.md => docs/ROADMAP.md (98%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..47ee52e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,22 @@ +# Code owners for msgtrace-sdk +# +# These owners will be automatically requested for review +# when someone opens a pull request. + +# Default owner for everything +* @vilsonrodrigues + +# Documentation +/docs/ @vilsonrodrigues +*.md @vilsonrodrigues + +# CI/CD and automation +/.github/ @vilsonrodrigues +/scripts/ @vilsonrodrigues + +# Core SDK +/src/msgtrace/sdk/ @vilsonrodrigues +/src/msgtrace/core/ @vilsonrodrigues + +# Tests +/tests/ @vilsonrodrigues diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..30a1d55 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,91 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the information below. + + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of what the bug is. + placeholder: What happened? + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Install msgtrace-sdk + 2. Run code with '...' + 3. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: What should have happened? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: What actually happened instead? + validations: + required: true + + - type: textarea + id: code + attributes: + label: Code Example + description: Minimal code to reproduce the issue + render: python + placeholder: | + from msgtrace.sdk import Spans, MsgTraceAttributes + + # Your code here + + - type: input + id: version + attributes: + label: msgtrace-sdk Version + description: What version are you using? + placeholder: "1.0.0" + validations: + required: true + + - type: input + id: python-version + attributes: + label: Python Version + description: What Python version are you using? + placeholder: "3.11" + validations: + required: true + + - type: input + id: os + attributes: + label: Operating System + description: What OS are you running? + placeholder: "Ubuntu 22.04 / macOS 14 / Windows 11" + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other information that might be helpful (logs, screenshots, etc.) + placeholder: Add any other context about the problem here diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..fd8b485 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,61 @@ +name: Feature Request +description: Suggest an idea or enhancement +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! Please describe your idea below. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: Is your feature request related to a problem? Please describe. + placeholder: I'm frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like + placeholder: I would like to be able to... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Have you considered any alternative solutions or workarounds? + placeholder: I've tried... + + - type: textarea + id: use-case + attributes: + label: Use Case + description: Describe your use case and how this feature would help + placeholder: This would help me... + validations: + required: true + + - type: textarea + id: example + attributes: + label: Code Example (Optional) + description: If applicable, show how you'd like to use this feature + render: python + placeholder: | + from msgtrace.sdk import Spans + + # Your desired API usage + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other information that might be helpful + placeholder: Add any other context or screenshots about the feature request here diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..1f7d102 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,54 @@ +## Summary + + + +## Changes + + +- +- +- + +## Type of Change + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Test improvement +- [ ] CI/CD improvement +- [ ] Chore/maintenance + +## Testing + + +- [ ] Tests pass locally (`uv run pytest -v`) +- [ ] Added new tests for this change +- [ ] Updated existing tests + +## Documentation + + +- [ ] Updated README.md (if API changed) +- [ ] Updated CHANGELOG.md (if notable change) +- [ ] Added/updated code comments +- [ ] Added/updated docstrings + +## Checklist + + +- [ ] Code formatted (`uv run ruff format`) +- [ ] Lint checks pass (`uv run ruff check`) +- [ ] Tests pass (`uv run pytest -v`) +- [ ] **Version NOT changed** (maintainers bump version after merge) +- [ ] Commit messages follow [conventional commits](https://www.conventionalcommits.org/) +- [ ] No breaking changes (or documented above) +- [ ] Added tests for new features +- [ ] Documentation is up to date + +## Additional Notes + + diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index fc162bb..af52ec2 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -2,36 +2,49 @@ name-template: 'v$RESOLVED_VERSION' tag-template: 'v$RESOLVED_VERSION' categories: + - title: '🚹 Breaking Changes' + labels: + - 'breaking-change' + - 'breaking' - title: '🚀 Features' labels: - 'enhancement' - 'feat' + - 'feature' - title: '🐛 Bug Fixes' labels: - 'bug' - 'fix' + - title: '⚡ Performance' + labels: + - 'performance' + - 'perf' + - title: '🔐 Security' + labels: + - 'security' - title: '📚 Documentation' labels: - 'documentation' - 'docs' + - title: '🔄 Refactoring' + labels: + - 'refactor' + - 'refactoring' - title: 'đŸ§Ș Tests' labels: - 'tests' - 'test' - - title: '⚡ Performance' + - title: 'đŸ€– CI/CD' labels: - - 'performance' - - 'perf' + - 'ci' + - 'ci-cd' + - title: '📩 Dependencies' + labels: + - 'dependencies' - title: '🔧 Maintenance' labels: - 'maintenance' - 'chore' - - title: '🔐 Security' - labels: - - 'security' - - title: '📩 Dependencies' - labels: - - 'dependencies' change-template: '- $TITLE @$AUTHOR (#$NUMBER)' change-title-escapes: '\<*_&' diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..dd43cdd --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,22 @@ +default_install_hook_types: [pre-commit, pre-push] + +repos: + # Security: Detect secrets and credentials + - repo: https://github.com/gitleaks/gitleaks + rev: v8.23.1 + hooks: + - id: gitleaks + + # UV: Keep uv.lock in sync + - repo: https://github.com/astral-sh/uv-pre-commit + rev: 0.8.3 + hooks: + - id: uv-lock + + # Ruff: Linting and formatting + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.11.7 + hooks: + - id: ruff + args: [--fix] + - id: ruff-format diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3622a15..803b66d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -491,6 +491,67 @@ https://github.com/msgflux/msgtrace-sdk/settings/secrets/actions - `PYPI_API_TOKEN` - From https://pypi.org/manage/account/token/ - `TEST_PYPI_API_TOKEN` - From https://test.pypi.org/manage/account/token/ +## 📩 Development Setup + +### Setup + +```bash +# Clone repository +git clone https://github.com/msgflux/msgtrace-sdk.git +cd msgtrace-sdk + +# Install dependencies +uv sync + +# Install with dev dependencies +uv sync --group dev +``` + +### Testing + +```bash +# Run tests +uv run pytest -v + +# With coverage +uv run pytest -v --cov=src/msgtrace --cov-report=html + +# Run specific test +uv run pytest tests/test_attributes.py -v +``` + +### Code Quality + +```bash +# Format code +uv run ruff format + +# Lint +uv run ruff check + +# Auto-fix +uv run ruff check --fix +``` + +### CI/CD + +The project uses GitHub Actions for CI/CD: + +- **CI** (`ci.yml`) - Lint, format, test on Python 3.10-3.13 +- **Validate Release** (`validate-release.yml`) - Security validation for releases +- **Publish** (`publish.yml`) - Publishes to PyPI after validation +- **Merge Bot** (`merge-bot.yml`) - Command-based PR merging with `/merge` and `/update` +- **Stale Bot** (`stale.yml`) - Closes stale issues/PRs +- **Release Drafter** (`release-drafter.yml`) - Auto-generates release notes +- **CodeQL** (`codeql.yml`) - Security scanning +- **Dependabot** - Automated dependency updates + +See [AUTOMATION.md](docs/AUTOMATION.md) for detailed automation documentation. + +### Release Process + +To release a new version, use the automated release script. See the "For Maintainers: Creating Releases" section above for detailed instructions. + ## 📚 Resources - [Conventional Commits](https://www.conventionalcommits.org/) @@ -499,3 +560,5 @@ https://github.com/msgflux/msgtrace-sdk/settings/secrets/actions - [Ruff Documentation](https://docs.astral.sh/ruff/) - [pytest Documentation](https://docs.pytest.org/) - [GitHub Actions](https://docs.github.com/en/actions) +- [Automation Guide](docs/AUTOMATION.md) +- [Roadmap](docs/ROADMAP.md) diff --git a/MERGE_BOT_GUIDE.md b/MERGE_BOT_GUIDE.md deleted file mode 100644 index 676fc1f..0000000 --- a/MERGE_BOT_GUIDE.md +++ /dev/null @@ -1,234 +0,0 @@ -# đŸ€– Merge Bot Guide - -Estilo PyTorch! Use comandos de comentĂĄrio para mergear PRs. - -## Como Usar - -### Opção 1: Mencionar o bot - -Comente no PR: - -``` -@mergebot merge -``` - -ou - -``` -@merge-bot merge -``` - -### Opção 2: Comando simples - -Comente no PR: - -``` -/merge -``` - -ou simplesmente: - -``` -merge -``` - -## O que acontece - -1. **Bot reage com 🚀** - Mostra que estĂĄ processando -2. **Verifica permissĂ”es** - SĂł colaboradores com acesso write/admin podem mergear -3. **Verifica se PR estĂĄ pronto** - NĂŁo pode ser draft, nĂŁo pode ter conflitos -4. **Aguarda checks** - Espera atĂ© 10 minutos por CI, testes, CodeQL, etc. -5. **Faz merge** - Usa squash merge -6. **Deleta branch** - Remove branch automaticamente -7. **Bot reage com 👍** - Confirma sucesso - -## Exemplo Completo - -``` -# VocĂȘ comenta: -@mergebot merge - -# Bot responde com emoji 🚀 - -# Bot aguarda CI passar... - -# CI passa ✅ - -# Bot comenta: -✅ PR merged successfully by @seu-usuario! - -# Bot adiciona emoji 👍 no seu comentĂĄrio -``` - -## Requisitos - -- ✅ VocĂȘ deve ter acesso de **write** ou **admin** no repo -- ✅ PR nĂŁo pode ser draft -- ✅ PR nĂŁo pode ter conflitos -- ✅ Todos os checks devem passar (ou bot aguarda atĂ© 10min) - -## Mensagens de Erro - -### ❌ Sem permissĂŁo - -``` -❌ @usuario you don't have permission to merge PRs. -Only collaborators with write access can use merge commands. -``` - -**Solução**: Peça a um maintainer para mergear. - -### ❌ PR Ă© draft - -``` -❌ Cannot merge: PR is still a draft. -Please mark it as ready for review first. -``` - -**Solução**: Clique em "Ready for review" no PR. - -### ❌ Conflitos - -``` -❌ Cannot merge: PR has conflicts or is not mergeable. -Please resolve conflicts first. -``` - -**Solução**: Resolva os conflitos manualmente. - -### ❌ Checks falharam - -``` -❌ Cannot merge: The following checks failed: - -- ❌ Ruff Lint & Format -- ❌ Test Python 3.10 - -Please fix the issues and try again. -``` - -**Solução**: Corrija os erros e faça push novamente. - -### ⏱ Timeout - -``` -⏱ Timeout waiting for checks to complete (waited 10 minutes). - -You can try the merge command again once checks complete. -``` - -**Solução**: Aguarde checks completarem e tente novamente. - -## Comparação com Auto-Merge - -| Feature | Auto-Merge (label) | Merge Bot (comando) | -|---------|-------------------|---------------------| -| Como ativar | Adicionar label `automerge` | Comentar `@mergebot merge` | -| Quando merge | Automaticamente quando CI passa | Quando vocĂȘ pedir explicitamente | -| Bom para | Dependabot, PRs triviais | PRs que precisam review manual | -| Controle | AutomĂĄtico | Manual (vocĂȘ escolhe quando) | - -## Quando Usar Cada Um - -### Use Auto-Merge (label) para: -- ✅ PRs do Dependabot -- ✅ Pequenas mudanças de docs -- ✅ Fixes triviais - -### Use Merge Bot (comando) para: -- ✅ PRs grandes que vocĂȘ reviewou -- ✅ Quando quer controle explĂ­cito -- ✅ Quando precisa aguardar algo especĂ­fico - -## Comandos Suportados - -Todas essas variaçÔes funcionam: - -```bash -@mergebot merge -@merge-bot merge -/merge -merge -``` - -(Case-insensitive, espaços extras sĂŁo ignorados) - -## Segurança - -- 🔒 SĂł colaboradores com **write access** podem usar -- 🔒 Verifica branch protection rules -- 🔒 Aguarda todos os checks obrigatĂłrios -- 🔒 NĂŁo pode mergear PRs com conflitos -- 🔒 NĂŁo pode mergear drafts - -## Exemplos de Uso - -### Exemplo 1: Review + Merge - -```markdown -# VocĂȘ reviewa o PR, aprova - -# Depois comenta: -LGTM! @mergebot merge - -# Bot faz o resto -``` - -### Exemplo 2: Aguardar CI - -```markdown -# CI ainda rodando... - -# VocĂȘ comenta: -@mergebot merge - -# Bot aguarda CI terminar (atĂ© 10min) -# Se passar, faz merge automaticamente -``` - -### Exemplo 3: Tentar novamente apĂłs fix - -```markdown -# CI falhou, vocĂȘ fixou - -# Comenta: -Fixed! /merge - -# Bot aguarda novo CI passar e faz merge -``` - -## Dicas - -💡 **Combine com reviews**: Aprove o PR e use `@mergebot merge` no mesmo comentĂĄrio - -💡 **Use em qualquer comentĂĄrio**: NĂŁo precisa ser o Ășltimo, bot detecta em qualquer comentĂĄrio - -💡 **Bot Ă© patient**: Aguarda atĂ© 10 minutos por checks, nĂŁo precisa ficar esperando - -💡 **Falhou? Tente de novo**: Se algo deu errado, basta comentar novamente - -## Troubleshooting - -### Bot nĂŁo respondeu - -1. Verifique se comentou **no PR** (nĂŁo em issue) -2. Verifique se usou um dos comandos corretos -3. Verifique logs em Actions → Merge Bot - -### Bot falhou - -Veja o log do workflow: -```bash -gh run list --workflow="Merge Bot" --limit 5 -gh run view --log -``` - -## Configuração - -Workflow: `.github/workflows/merge-bot.yml` - -Para modificar: -- Tempo de espera (padrĂŁo: 10 minutos) -- Merge method (padrĂŁo: squash) -- Comandos aceitos -- PermissĂ”es necessĂĄrias diff --git a/README.md b/README.md index 594c003..630ff4d 100644 --- a/README.md +++ b/README.md @@ -605,58 +605,15 @@ When `MSGTRACE_TELEMETRY_ENABLED=false`: - No-op tracer is created (minimal overhead) - Attribute setters check `span.is_recording()` (fast path) -## Development +## Contributing -### Setup +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: +- Development setup +- Testing and code quality guidelines +- Pull request process +- Release workflow -```bash -# Clone repository -git clone https://github.com/msgflux/msgtrace-sdk.git -cd msgtrace-sdk - -# Install dependencies -uv sync - -# Install with dev dependencies -uv sync --group dev -``` - -### Testing - -```bash -# Run tests -uv run pytest -v - -# With coverage -uv run pytest -v --cov=src/msgtrace --cov-report=html - -# Run specific test -uv run pytest tests/test_attributes.py -v -``` - -### Code Quality - -```bash -# Format code -uv run ruff format - -# Lint -uv run ruff check - -# Auto-fix -uv run ruff check --fix -``` - -### CI/CD - -The project uses GitHub Actions for CI/CD: - -- **CI** (`ci.yml`) - Lint, format, test on Python 3.10-3.13 -- **Version Validation** (`validate-version-bump.yml`) - Validates version bumps on PRs -- **Auto-Tag** (`auto-tag.yml`) - Creates git tags on version changes -- **Publish** (`publish.yml`) - Publishes to TestPyPI and PyPI - -To release a new version, update `src/msgtrace/version.py` and open a PR. On merge, the version is automatically tagged and published to PyPI. +For automation details (CI/CD, bots, etc.), see [AUTOMATION.md](docs/AUTOMATION.md). ## License diff --git a/AUTOMATION.md b/docs/AUTOMATION.md similarity index 68% rename from AUTOMATION.md rename to docs/AUTOMATION.md index 3772e74..70bc5ac 100644 --- a/AUTOMATION.md +++ b/docs/AUTOMATION.md @@ -44,6 +44,7 @@ This document describes all automated workflows configured for msgtrace-sdk. **What it does**: - Merges PRs via comment commands (PyTorch-style) +- Updates PR branches with latest changes from base branch - Waits up to 10 minutes for CI checks to pass - Checks user permissions (write/admin only) - Uses squash merge @@ -51,12 +52,130 @@ This document describes all automated workflows configured for msgtrace-sdk. - Interactive feedback with emoji reactions **Commands**: + +**Merge Commands**: - `@mergebot merge` - `@merge-bot merge` - `/merge` - `merge` -**See**: `MERGE_BOT_GUIDE.md` for detailed usage +**Update Commands** (new in v1.0.0): +- `@mergebot update` +- `@merge-bot update` +- `/update` +- `update` + +#### How to Use the Merge Bot + +**Option 1: Mention the bot** +``` +@mergebot merge +``` +or +``` +@merge-bot merge +``` + +**Option 2: Simple command** +``` +/merge +``` +or simply: +``` +merge +``` + +**What happens when you merge:** +1. Bot reacts with 🚀 - Shows it's processing +2. **Checks permissions** - Only collaborators with write/admin can merge +3. **Checks if PR is ready** - Can't be draft, can't have conflicts +4. **Waits for checks** - Waits up to 10 minutes for CI, tests, CodeQL, etc. +5. **Merges PR** - Uses squash merge +6. **Deletes branch** - Removes branch automatically +7. Bot reacts with 👍 - Confirms success + +**Update Command Usage:** + +Use `/update` or `@mergebot update` to update your PR branch with the latest changes from the base branch (usually `main`). This is useful when your PR is behind the base branch. + +**What happens when you update:** +1. Bot reacts with 👀 - Shows it's processing +2. **Checks permissions** - Only collaborators with write/admin can update +3. **Merges base branch** - Merges latest changes from base into PR branch +4. **Pushes changes** - Automatically pushes to your PR branch +5. **Comments with status** - Confirms success or failure +6. Bot reacts with 👍 (success) or 👎 (failure) + +**Example:** +``` +# PR is behind main branch + +# You comment: +/update + +# Bot merges main into your PR branch +# Bot comments: "✅ Branch updated successfully by @username!" +``` + +**Requirements:** +- ✅ You must have **write** or **admin** access to the repo +- ✅ PR cannot be a draft (for merge) +- ✅ PR cannot have conflicts (for merge) +- ✅ All checks must pass (or bot waits up to 10 min for merge) + +**Error Messages:** + +**❌ No permission** +``` +❌ @user you don't have permission to merge/update PRs. +Only collaborators with write access can use these commands. +``` +**Solution**: Ask a maintainer. + +**❌ PR is draft** +``` +❌ Cannot merge: PR is still a draft. +Please mark it as ready for review first. +``` +**Solution**: Click "Ready for review" on the PR. + +**❌ Conflicts** +``` +❌ Cannot merge: PR has conflicts or is not mergeable. +Please resolve conflicts first. +``` +**Solution**: Resolve conflicts manually. + +**❌ Checks failed** +``` +❌ Cannot merge: The following checks failed: +- ❌ Ruff Lint & Format +- ❌ Test Python 3.10 +Please fix the issues and try again. +``` +**Solution**: Fix errors and push again. + +**❌ Update conflicts** +``` +❌ Failed to update branch with latest changes from `main`. + +This usually means there are merge conflicts that need to be resolved manually. +``` +**Solution**: Merge main locally and resolve conflicts. + +**⏱ Timeout** +``` +⏱ Timeout waiting for checks to complete (waited 10 minutes). +You can try the merge command again once checks complete. +``` +**Solution**: Wait for checks to complete and try again. + +**Security:** +- 🔒 Only collaborators with **write access** can use commands +- 🔒 Respects branch protection rules +- 🔒 Waits for all required checks +- 🔒 Cannot merge PRs with conflicts +- 🔒 Cannot merge drafts --- diff --git a/ROADMAP.md b/docs/ROADMAP.md similarity index 98% rename from ROADMAP.md rename to docs/ROADMAP.md index 4d8c38d..3cb193a 100644 --- a/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,7 +2,7 @@ Planned features for future releases. -## v0.2.0 - Sampling and Performance +## v1.1.0 - Sampling and Performance ### Trace Sampling Add support for trace sampling to reduce overhead in high-volume production environments. From f0e112e6c3a2cf4fbfd588dd78a355abd860ee37 Mon Sep 17 00:00:00 2001 From: Vilson Rodrigues Date: Thu, 27 Nov 2025 17:42:09 -0300 Subject: [PATCH 2/3] Fix merge-bot update command checkout issue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The update command was failing because the checkout action wasn't specifying which repository to checkout from. This caused it to only fetch the default branches and not the PR branch. Added 'repository' parameter to the checkout action to explicitly specify the head repository, fixing the branch checkout issue. Same fix as applied to msgspec-ext repository. đŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/merge-bot.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/merge-bot.yml b/.github/workflows/merge-bot.yml index c79d5d7..00248a1 100644 --- a/.github/workflows/merge-bot.yml +++ b/.github/workflows/merge-bot.yml @@ -403,6 +403,7 @@ jobs: if: steps.check_perms.outputs.has_permission == 'true' uses: actions/checkout@v4 with: + repository: ${{ steps.pr_info.outputs.head_repo }} ref: ${{ steps.pr_info.outputs.head_branch }} fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} From 0827834461548d2174937752581827ff86af657a Mon Sep 17 00:00:00 2001 From: Vilson Rodrigues Date: Thu, 4 Dec 2025 18:15:34 -0300 Subject: [PATCH 3/3] feat: add module, tool execution, and agent response attributes Add new attribute setters for: - Module attributes (name, type) for specialized visualizations - Extended tool attributes (execution type, protocol) - Extended agent attributes (response content) These attributes enable better categorization and visualization of AI operations in the msgtrace frontend. --- src/msgtrace/sdk/attributes.py | 69 ++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/src/msgtrace/sdk/attributes.py b/src/msgtrace/sdk/attributes.py index 4de7628..fad6285 100644 --- a/src/msgtrace/sdk/attributes.py +++ b/src/msgtrace/sdk/attributes.py @@ -449,6 +449,75 @@ def set_version(version: str): if span.is_recording(): span.set_attribute("version", version) + # ========== Module Attributes ========== + + @staticmethod + def set_module_name(name: str): + """ + Set module name. + + Args: + name: Module name (e.g., 'vector_search', 'intent_classifier') + """ + span = trace.get_current_span() + if span.is_recording(): + span.set_attribute("module.name", name) + + @staticmethod + def set_module_type(module_type: str): + """ + Set module type for specialized visualizations. + + Args: + module_type: Type (e.g., 'Agent', 'Tool', 'LLM', 'Transcriber', 'Retriever') + """ + span = trace.get_current_span() + if span.is_recording(): + span.set_attribute("module.type", module_type) + + # ========== Extended Tool Attributes ========== + + @staticmethod + def set_tool_execution_type(execution_type: str): + """ + Set tool execution type. + + Args: + execution_type: Execution type (e.g., 'local', 'remote') + """ + span = trace.get_current_span() + if span.is_recording(): + span.set_attribute("gen_ai.tool.execution.type", execution_type) + + @staticmethod + def set_tool_protocol(protocol: str): + """ + Set tool protocol. + + Args: + protocol: Protocol (e.g., 'mcp', 'a2a', 'http', 'grpc') + """ + span = trace.get_current_span() + if span.is_recording(): + span.set_attribute("gen_ai.tool.protocol", protocol) + + # ========== Extended Agent Attributes ========== + + @staticmethod + def set_agent_response(response: str | dict[str, Any]): + """ + Set agent response content. + + Args: + response: Agent response as string or dict + """ + span = trace.get_current_span() + if span.is_recording(): + if isinstance(response, str): + span.set_attribute("gen_ai.agent.response", response) + else: + span.set_attribute("gen_ai.agent.response", json.dumps(response)) + # ========== Generic Custom Attributes (MsgTrace) ========== @staticmethod