{"id":47111117,"url":"https://github.com/systelab/cpp-trace-api","last_synced_at":"2026-03-12T17:46:05.725Z","repository":{"id":90260532,"uuid":"222799650","full_name":"systelab/cpp-trace-api","owner":"systelab","description":"C++ trace system","archived":false,"fork":false,"pushed_at":"2025-03-20T15:21:32.000Z","size":139,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-20T15:34:07.320Z","etag":null,"topics":["cpp-library"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systelab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-11-19T22:11:37.000Z","updated_at":"2022-07-23T22:29:59.000Z","dependencies_parsed_at":"2023-07-25T23:46:05.558Z","dependency_job_id":null,"html_url":"https://github.com/systelab/cpp-trace-api","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/systelab/cpp-trace-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systelab%2Fcpp-trace-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systelab%2Fcpp-trace-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systelab%2Fcpp-trace-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systelab%2Fcpp-trace-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systelab","download_url":"https://codeload.github.com/systelab/cpp-trace-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systelab%2Fcpp-trace-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30436020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cpp-library"],"created_at":"2026-03-12T17:46:02.427Z","updated_at":"2026-03-12T17:46:05.709Z","avatar_url":"https://github.com/systelab.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/systelab/cpp-trace-api.svg?branch=master)](https://travis-ci.org/systelab/cpp-trace-api)\n[![Build status](https://ci.appveyor.com/api/projects/status/h5mevc6dpunulq13?svg=true)](https://ci.appveyor.com/project/systelab/cpp-trace-api)\n[![codecov](https://codecov.io/gh/systelab/cpp-trace-api/branch/master/graph/badge.svg)](https://codecov.io/gh/systelab/cpp-trace-api)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/afb821612838478bb85fff39a7fe5b88)](https://www.codacy.com/gh/systelab/cpp-trace-api/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=systelab/cpp-trace-api\u0026amp;utm_campaign=Badge_Grade)\n\n\n# C++ Trace System\n\nThis library provides utilities to easily add traces to your application.\n\n## Supported features\n\n* Multiple channels\n* Dump to .log files\n* Dedicated threads\n* Built-in fields\n* Channel enabling/disabling\n* Severity filtering\n* Backup generation\n* Deletion of old backups (rolling basis)\n\n\n## Setup\n\n### Download using Conan\n\nThis library is designed to be installed by making use of [Conan](https://conan.io/) package manager. So, you just need to add the following requirement into your Conan recipe:\n\n```python\ndef requirements(self):\n   self.requires(\"TraceAPI/1.0.0@systelab/stable\")\n```\n\n\u003e Version number of this code snipped is set just as an example. Replace it for the desired package to retrieve.\n\nAs this package is not available on the conan-center, you will also need to configure a remote repository before installing dependencies:\n\n```bash\nconan remote add systelab-public https://systelab.jfrog.io/artifactory/api/conan/cpp-conan-production-local\n```\n\nSee Conan [documentation](https://docs.conan.io/en/latest/) for further details on how to integrate this package with your build system.\n\n### Build from sources\n\nSee [BUILD.md](BUILD.md) document for details.\n\n\n## Usage\n\n### Set up a file agent\n\nFor each channel of traces to set up, a `systelab::trace::FileAgent` needs to be instantiated. \n\nThe constructor parameter of this class requires a configuration object where the trace channel particularities are defined:\n* Channel name\n* Path of logs base folder\n* Rotation folders prefix\n* Maximum number of rotation folders\n* ...\n\n```cpp\n#include \"TraceAPI/Configuration.h\"\n#include \"TraceAPI/FileAgent.h\"\n\nauto configuration = std::make_unique\u003csystelab::trace::Configuration\u003e();\nconfiguration-\u003esetChannelName(\"MyChannel\");\nconfiguration-\u003esetBaseFolderPath(\"./Subfolder/MyTraces\");\nconfiguration-\u003esetMaxRotationDays(3);\n\t\t\t\nauto fileAgent = std::make_unique\u003csystelab::trace::FileAgent\u003e(std::move(configuration));\n```\n\n\u003e The agent instance must be kept alive (not destroyed) during the whole application lifecycle. Thus, all traces added when there is no agent instance won't be recorded on the file.\n\n### Add a trace\n\nTraces can be added using the `TRACE_CHANNEL` macro providing:\n* Channel name as an argument\n* Trace content through the stream (`\u003c\u003c`) operator\n\n```cpp\n#include \"TraceAPI/ChannelMacro.h\"\n\nTRACE_CHANNEL(\"MyChannel\") \u003c\u003c \"This is the trace number \" \u003c\u003c 1 \u003c\u003c \" to add\";\n```\n\nIt is highly recommended to define your own macros to easily trace to an specific channel:\n\n```cpp\n#define TRACE_MY_CHANNEL() \\\n    TRACE_CHANNEL(\"MyChannel\")\n```\n\nThen, traces can be added as follows:\n\n```cpp\nTRACE_MY_CHANNEL() \u003c\u003c \"Trace added using custom macro.\";\n```\n\n### Built-in fields\n\nThe library is also prepared to record the severity and a tag value for each trace added.\n\nAs the usage of these fields is optional, the library provides specific macros designed for that purpose:\n\n```cpp\n#include \"TraceAPI/ChannelMacro.h\"\n\nTRACE_CHANNEL_SEVERITY(\"MyChannel\", \"INFO\") \u003c\u003c \"This is a trace with 'INFO' severity\";\nTRACE_CHANNEL_TAG(\"MyChannel\", \"MY_TAG\") \u003c\u003c \"This is a trace with 'MY_TAG' tag\";\nTRACE_CHANNEL_SEVERITY_TAG(\"MyChannel\", \"ERROR\", \"TAG2\") \u003c\u003c \"An error trace with 'TAG2' tag\";\n```\n\n### Rotation\n\nTrace files are automatically rotated at midnight. However, if you want to force a log file rotation, just call the `rotate()` method of the associated `FileAgent` entity.\n\n```cpp\nfileAgent-\u003erotate();\n```\n\nThat would move the current traces file into a `Logs_YYYY_MM_DD` subfolder, where `YYYY`, `MM` and `DD` respectively correspond with the year, month and day of the current date. In order to allow archiving of multiple trace files for the same day, a timestamp is appended to trace the filename.\n\nAdditionally, old backups are automatically deleted, so only the configured amount of rotation days folders is kept.\n\nPrefix of rotation folders can be customized by means of the `setRotationFoldersPrefix` of the configuration object (by default, it is set to `Logs`):\n\n```cpp\nconfiguration-\u003esetRotationFoldersPrefix(\"MyPrefix\");\n```\n\n### Channel disabling\n\nA channel can be temporarilly disabled by using the `enable()` method of the associated file agent:\n\n```cpp\nfileAgent-\u003eenable(false);\n```\n\nSimilarly, the channel can be reenabled as follows:\n\n```cpp\nfileAgent-\u003eenable(true);\n```\n\n### Severity filtering\n\nThis library allows defining which severity levels will be logged on the trace files. These severities are set using the `setSeverityFilter()` method of the configuration object:\n\n```cpp\nstd::vector\u003cstd::string\u003e severityFilter = {\"ERROR\", \"WARNING\"};\nconfiguration-\u003esetSeverityFilter(severityFilter);\n```\n\n\u003e By default (when no filter is configured), traces for any severity level are added to files.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystelab%2Fcpp-trace-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystelab%2Fcpp-trace-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystelab%2Fcpp-trace-api/lists"}