{"id":26949694,"url":"https://github.com/devops-360-online/test-library","last_synced_at":"2025-04-02T22:17:21.094Z","repository":{"id":284716678,"uuid":"955811867","full_name":"devops-360-online/test-library","owner":"devops-360-online","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-27T10:13:33.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-27T10:27:51.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devops-360-online.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-27T08:34:00.000Z","updated_at":"2025-03-27T10:13:36.000Z","dependencies_parsed_at":"2025-03-27T10:38:03.481Z","dependency_job_id":null,"html_url":"https://github.com/devops-360-online/test-library","commit_stats":null,"previous_names":["devops-360-online/test-library"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-360-online%2Ftest-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-360-online%2Ftest-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-360-online%2Ftest-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-360-online%2Ftest-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devops-360-online","download_url":"https://codeload.github.com/devops-360-online/test-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246899652,"owners_count":20851899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-02T22:17:20.507Z","updated_at":"2025-04-02T22:17:21.076Z","avatar_url":"https://github.com/devops-360-online.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Mini-Telemetry: Une bibliothèque minimaliste pour OpenTelemetry\n\nCette bibliothèque simplifie l'utilisation d'OpenTelemetry en fournissant une interface minimaliste pour configurer et exposer les outils d'observabilité (traces, logs et métriques).\n\n## Qu'est-ce qu'OpenTelemetry?\n\nOpenTelemetry est un framework standard, open-source, pour collecter et envoyer des données d'observabilité (traces, métriques et logs) à partir de vos applications.\n\n### Les trois piliers de l'observabilité\n\n1. **Traces**: Suivent le flux d'exécution à travers les composants de votre application\n2. **Métriques**: Capturent des valeurs numériques sur l'état et la performance\n3. **Logs**: Enregistrent des événements et des messages textuels\n\n### Avantages d'OpenTelemetry\n\n- **Standard ouvert**: Compatible avec de nombreux fournisseurs\n- **Pas de verrouillage**: Vous pouvez changer de backend d'analyse à tout moment\n- **Intégré**: Corrèle naturellement les traces, métriques et logs\n- **Extensible**: Fonctionne avec tous les langages et frameworks\n\n## Installation\n\n```bash\npip install opentelemetry-api opentelemetry-sdk\n```\n\n## Utilisation de base\n\n```python\nfrom mini_telemetry import TelemetryTools\n\n# 1. Initialisation (fait une seule fois)\ntelemetry = TelemetryTools(\n    service_name=\"mon-service\",\n    service_version=\"1.0.0\",\n    environment=\"production\"\n)\n\n# 2. Obtenir les outils pour chaque composant\ntracer = telemetry.get_tracer(\"mon.module\")\nmeter = telemetry.get_meter(\"mon.module\")\nlogger = telemetry.get_logger(\"mon.module\")\n\n# 3. Utiliser ces outils dans votre code\n```\n\n## Exportation des données\n\n**Mini-Telemetry exporte exclusivement vers stdout (la sortie standard)**:\n\n- **Aucun composant externe requis** pour visualiser les données\n- **Tout apparaît directement dans la console/terminal**\n- **Parfait pour le développement et le debug**\n- Un autre composant séparé peut collecter cette sortie si nécessaire (Filebeat, Fluentd, etc.)\n\nFormat des sorties:\n1. **Logs**: Texte formaté ou JSON, avec IDs de trace\n2. **Traces**: JSON formaté avec structure de span complète\n3. **Métriques**: JSON formaté avec valeurs et timestamps\n\nCette approche minimaliste permet de:\n- Commencer immédiatement sans infrastructure complexe\n- Voir toutes les données au même endroit\n- Utiliser les outils standard de redirection UNIX si nécessaire (`\u003e file.log`)\n- Intégrer facilement à des conteneurs Docker ou des environnements cloud\n\n## Guide des concepts OpenTelemetry\n\n### Traces et Spans\n\nUne **trace** représente le chemin d'exécution complet à travers le système. Elle est composée de **spans** interconnectés.\n\nUn **span** représente une opération unique dans votre code avec:\n- Un nom\n- Un temps de début/fin\n- Des attributs (clé-valeur)\n- Des événements horodatés\n- Des liens vers d'autres spans\n- Un statut (succès/échec)\n\n```python\n# Créer un span parent\nwith tracer.start_as_current_span(\"opération-principale\") as span:\n    # Ajouter des attributs\n    span.set_attribute(\"utilisateur.id\", \"123\")\n    \n    # Effectuer l'opération...\n    \n    # Créer un span enfant (sous-opération)\n    with tracer.start_as_current_span(\"sous-opération\") as child:\n        # Opération enfant...\n        pass\n    \n    # Enregistrer un événement\n    span.add_event(\"événement-important\", {\"détail\": \"valeur\"})\n    \n    # Définir le statut\n    span.set_status(trace.Status(trace.StatusCode.OK))\n```\n\n### Métriques\n\nLes métriques sont des mesures numériques collectées sur une période. Types principaux:\n\n1. **Compteur**: Valeur qui ne peut qu'augmenter (ex: nombre de requêtes)\n2. **Histogramme**: Distribution de valeurs (ex: temps de réponse)\n3. **Jauge**: Valeur qui peut augmenter/diminuer (ex: utilisation mémoire)\n\n```python\n# Créer un compteur\ncounter = meter.create_counter(\n    name=\"requêtes\",\n    description=\"Nombre de requêtes traitées\",\n    unit=\"1\"  # Pas d'unité spécifique\n)\n\n# Incrémenter le compteur (avec attributs)\ncounter.add(1, {\"endpoint\": \"/api\", \"méthode\": \"GET\"})\n\n# Créer un histogramme\nhistogram = meter.create_histogram(\n    name=\"latence\",\n    description=\"Temps de réponse des requêtes\",\n    unit=\"ms\"  # Millisecondes\n)\n\n# Enregistrer une valeur\nhistogram.record(42.5, {\"endpoint\": \"/api\"})\n```\n\n### Logs avec contexte de trace\n\nLes logs peuvent être enrichis avec les identifiants de trace et de span, permettant de les corréler avec les traces:\n\n```python\n# Le logger est configuré pour ajouter automatiquement les IDs de trace et span\nlogger.info(\"Traitement démarré\")\nlogger.error(\"Une erreur s'est produite\", exc_info=True)\n\n# Avec contexte supplémentaire\nlogger.info(\"Opération terminée\", extra={\"durée_ms\": 123, \"status\": \"success\"})\n```\n\n## Corrélation entre traces, métriques et logs\n\nLa corrélation est l'un des aspects les plus puissants d'OpenTelemetry:\n\n1. **Logs → Traces**: Les logs incluent automatiquement des IDs de trace/span\n2. **Traces → Métriques**: Les attributs de span peuvent être appliqués aux métriques\n3. **Métriques → Traces**: Les problèmes détectés dans les métriques peuvent être explorés via les traces associées\n\nExemple de log avec contexte de trace:\n```\n2023-03-27 14:23:45 [INFO] mon.module - trace_id=abcdef0123456789 span_id=0123456789abcdef - Message\n```\n\n## Bonnes pratiques\n\n1. **Conventions de nommage**:\n   - Services: `com.entreprise.service`\n   - Spans: `opération.action` (ex: `http.request`, `db.query`)\n   - Métriques: `domaine.objet.mesure` (ex: `http.server.duration_ms`)\n\n2. **Attributs cohérents**: Utilisez les mêmes attributs pour les spans et métriques associées\n```python\n# Dans un span\nspan.set_attribute(\"endpoint\", \"/api/users\")\n\n# Dans une métrique (même attribut)\ncounter.add(1, {\"endpoint\": \"/api/users\"})\n```\n\n3. **Granularité des spans**: \n   - Créez des spans pour les opérations significatives\n   - Utilisez des spans imbriqués pour les sous-opérations\n   - Ne tracez pas les fonctions triviales\n\n4. **Gestion des erreurs**:\n```python\ntry:\n    # Code\nexcept Exception as e:\n    # Enregistrer l'exception dans le span\n    span.record_exception(e)\n    span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))\n    logger.error(f\"Erreur: {str(e)}\", exc_info=True)\n    raise\n```\n\n## Exemple complet\n\nVoir le fichier [mini_telemetry.py](mini_telemetry.py) pour un exemple complet de:\n- Configuration des outils\n- Instrumentation manuelle\n- Corrélation entre traces, métriques et logs\n\n## Extension à d'autres backends (optionnel)\n\nPar défaut, les traces, logs et métriques sont envoyés **uniquement à la console (stdout)**, sans nécessiter de composants externes.\n\nSi vous souhaitez ultérieurement exporter vers d'autres systèmes, voici comment procéder:\n\n- **Jaeger/Zipkin** pour les traces\n- **Prometheus** pour les métriques\n- **Elasticsearch** pour les logs\n\nExemple d'ajout d'exportateur OTLP:\n\n```python\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\n\n# Dans _setup_tracing()\notlp_exporter = OTLPSpanExporter(endpoint=\"http://collector:4317\")\nspan_processor = BatchSpanProcessor(otlp_exporter)\ntrace_provider.add_span_processor(span_processor)\n```\n\nCette extension est entièrement optionnelle et n'est recommandée que lorsque votre projet atteint une maturité nécessitant une infrastructure d'observabilité complète.\n\n## Ressources\n\n- [Documentation OpenTelemetry](https://opentelemetry.io/docs/)\n- [Spécification OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification)\n- [Conventions sémantiques](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions) ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-360-online%2Ftest-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevops-360-online%2Ftest-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-360-online%2Ftest-library/lists"}