{"id":19998073,"url":"https://github.com/git-ecosystem/sample-trace2-otel-collector","last_synced_at":"2025-10-16T13:32:27.398Z","repository":{"id":203341262,"uuid":"700075841","full_name":"git-ecosystem/sample-trace2-otel-collector","owner":"git-ecosystem","description":"A sample custom collector to contain trace2receiver and associated config and installer scripts","archived":false,"fork":false,"pushed_at":"2024-03-28T19:45:48.000Z","size":139,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-28T20:55:38.470Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/git-ecosystem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-03T22:31:08.000Z","updated_at":"2024-05-29T23:16:03.632Z","dependencies_parsed_at":null,"dependency_job_id":"9e72744c-5370-43d4-873f-e91a1e2fa29b","html_url":"https://github.com/git-ecosystem/sample-trace2-otel-collector","commit_stats":null,"previous_names":["git-ecosystem/sample-trace2-otel-collector"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ecosystem%2Fsample-trace2-otel-collector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ecosystem%2Fsample-trace2-otel-collector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ecosystem%2Fsample-trace2-otel-collector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ecosystem%2Fsample-trace2-otel-collector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-ecosystem","download_url":"https://codeload.github.com/git-ecosystem/sample-trace2-otel-collector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252349178,"owners_count":21733785,"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":"2024-11-13T05:07:17.733Z","updated_at":"2025-10-16T13:32:22.367Z","avatar_url":"https://github.com/git-ecosystem.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sample Trace2 OpenTelemetry Collector\n\nThis directory contains a sample custom collector to read\nTrace2 telemetry from Git commands, transform it into OTLP,\nand export it to various OpenTelemetry data sinks.\n\nYou can use this demonstration collector to quickly evaluate the\n[`trace2receiver`](https://github.com/git-ecosystem/trace2receiver)\ntechnology and before building your own telemetry solution.\n\nThe collector source code (`./*.go` and `./go.*`) distributed\nin this repository was generated automatically by the OpenTelemetry\nbuilder tool (as explained below). Its purpose is to quick start\nyour evaluation.\n\n* NOTE Once you become familiar with the technology,\nyou'll want to fork the repo, download the most recent version\nof the builder tool, and regenerate the source code. This is\nespecially true if you want to include other exporter components\nthat I didn't include in the demonstration version.\n\nAlso included in this repository is a set of Makefiles and scripts\nto build distribution/installer packages for the collector on each\nof the major platforms. The collector is designed to run as a\nlong-running service daemon and these scripts will help you\nstart building your own packages. These scripts cover the basic\nsetup, but omit some details, like package signing.\n\n* NOTE Before generating deployment packages, you'll want to:\n  * Configure your `config.yml` (as explained below) to talk to your chosen telemetry data sink or cloud provider.\n  * Create any additional `pii.yml`, `filter.yml`, and rulesets so that your distribution packages will be pre-configured when you deploy them to your users.\n  * Rename the example collector exectuable, pathnames, and assets to reflect your organization.\n\n\n\n## Generating/regenerating the sample collector\n\nThe GOLANG source was generated using the OpenTelemetry\n[builder](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder)\ntool and the `builder-config.yml` definition.  This YML file\ndefines the various receiver, pipeline, and exporter components\nthat will be statically linked into the custom collector executable.\nIf you want to add or remove a component, update the YML file\nand re-run the builder tool.\n\nYou should update the component versions listed in this YML file\nbefore running the builder tool, since the builder tool will generate\nthe `go.mod` file and you don't want it to start with obsolete\ndependencies.\n\n```\n$ GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@latest\n$ ~/go/bin/builder --config ./builder-config.yml\n$ go build\n$ go test\n```\n\nThe `builder-config.yml` file provided here contains a basic set of components to get you started.\nThe [`trace2receiver`](https://github.com/git-ecosystem/trace2receiver) component\nhas additional [details](https://github.com/git-ecosystem/trace2receiver/blob/main/Docs/).\n\nThe `go` commands will automatically pull in the `trace2receiver`\ncomponent as a dependent module in the normal GOLANG way. You may\nwant to update the version numbers of any dependent modules at this time.\n\n\n\n### Errors\n\nIf you see a warning like the following, update all of the pinned component versions in the `builder-config.yml` file to match the suggested version (by the newer version of the builder tool) and try again.\n\n```\n% ~/go/bin/builder --config ./builder-config.yml\n2023-11-16T12:30:23.932-0500\tINFO\tinternal/command.go:123\tOpenTelemetry Collector Builder\t{\"version\": \"dev\", \"date\": \"unknown\"}\n2023-11-16T12:30:23.934-0500\tINFO\tinternal/command.go:159\tUsing config file\t{\"path\": \"./builder-config.yml\"}\n2023-11-16T12:30:23.934-0500\tINFO\tbuilder/config.go:109\tUsing go\t{\"go-executable\": \"/usr/local/go/bin/go\"}\n2023-11-16T12:30:23.934-0500\tINFO\tbuilder/main.go:67\tYou're building a distribution with non-aligned version of the builder. Compilation may fail due to API changes. Please upgrade your builder or API\t{\"builder-version\": \"0.89.0\"}\n2023-11-16T12:30:23.937-0500\tINFO\tbuilder/main.go:91\tSources created\t{\"path\": \".\"}\n...\n```\n\nIn my case, I last used `v0.81.0` in my `builder-config.yml` file and upgraded the tool to `v0.89.0`, so I had a mismatch.\n\n```\n % git diff -- builder-config.yml\ndiff --git a/builder-config.yml b/builder-config.yml\nindex b011468..3b1e23e 100644\n--- a/builder-config.yml\n+++ b/builder-config.yml\n@@ -2,21 +2,21 @@ dist:\n   module: github.com/git-ecosystem/sample-trace2-otel-collector\n   name: sample-trace2-otel-collector\n   description: Custom OTEL Collector to convert and relay Git Trace2 data to OTLP\n-  otelcol_version: 0.81.0\n+  otelcol_version: 0.89.0\n   output_path: .\n   version: 0.0.0\n\n exporters:\n-  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/azuremonitorexporter v0.81.0\n+  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/azuremonitorexporter v0.89.0\n   - import: go.opentelemetry.io/collector/exporter/loggingexporter\n-    gomod: go.opentelemetry.io/collector v0.81.0\n+    gomod: go.opentelemetry.io/collector v0.89.0\n   - import: go.opentelemetry.io/collector/exporter/otlpexporter\n-    gomod: go.opentelemetry.io/collector v0.81.0\n+    gomod: go.opentelemetry.io/collector v0.89.0\n\n receivers:\n   - gomod: github.com/git-ecosystem/trace2receiver v0.4.3\n\n processors:\n   - import: go.opentelemetry.io/collector/processor/batchprocessor\n-    gomod: go.opentelemetry.io/collector v0.81.0\n+    gomod: go.opentelemetry.io/collector v0.89.0\n```\n\n\n\n## Configuring the sample collector\n\nOnce built, your collector requires another YML file to tell it which (of the\nstatically linked components) to actually instantiate, how to plumb data\nbetween them, and set any configuration parameters (such as cloud credentials\nfor your data sink(s) or other pathnames).\n\nThe `sample-configs/*/config.yml` files provided here contains a minimal set of components to log\ntelemetry to the console or system event viewer. They assume that:\n* On Linux and macOS: you will install the collector executable and\nthe various YML files into `/usr/local/sample-trace2-otel-collector/`.\n* On Windows: you will install the executable into `C:/Program Files/sample-trace2-otel-collector/` and\nthe various YML data files into `C:/ProgramData/sample-trace2-otel-collector/`.\n\n_(The named pipe pathname is not in the ProgramData directory, since\nnamed pipes must be created on the Named Pipe File System (NPFS) and\nhave the `//./pipe/` prefix.)_\n\nThe `trace2receiver` component has additional\n[details](https://github.com/git-ecosystem/trace2receiver/blob/main/Docs/configure-custom-collector.md)\nand several [examples](https://github.com/git-ecosystem/trace2receiver/tree/main/Docs/Examples).\n\n\n\n## Interactively running the sample collector (optional)\n\nIf you want, you can run the collector in a terminal window to test\nyour configuration. When interactive, the debug log will appear on the\nconsole. You can change the two logging verbosity settings in the `config.yml`\nfile to see the OTLP being emitted.\n\n```\n$ ./sample-trace2-otel-collector --config \u003cpathname-to-config.yml\u003e\n```\n\n_In addition to having a running the collector, listening on a Unix\nDomain Socket (SOCKET) or Windows Named Pipe (PIPE), you'll also need\nto tell Git to send telemetry to the collector using the\n`trace2.eventtarget` Git config variable (using `--system` or\n`--global` scope). The various installer `service_start` scripts show\nhow to do this._\n\n\n\n\n## Building sample installer packages\n\nThe provided `installer/\u003cplatform\u003e/Makefile` will build a minimal installer\npackage for your platform.\n\n### On macOS\n\nTo build an installer PKG on macOS:\n\n```\n$ go build\n$ cd ./installer/\u003cplatform\u003e\n$ make layout\n$ make package\n```\n\nA \".pkg\" will be created in `./installer/macos/_out_/_pkg_/`.  You can use it to\ninstall the sample collector in `/usr/local/sample-trace2-otel-collector/*`.\nThe installer script will copy the files, register it with `launchctl(1)`,\nand start it.\n\nThe scripts in `/usr/local/sample-trace2-otel-collector/scripts/*` let you\nstop and restart the service. Use these if you want to try different settings\nin your installed `config.yml` or other YML files (such as `filter.yml`).\n\nThe `/usr/local/sample-trace2-otel-collector/uninstaller.sh` script will stop\nthe service and delete it.\n\n\n### On Linux\n\nTo build an installer DEB on Linux:\n\n```\n$ go build\n$ cd ./installer/\u003cplatform\u003e\n$ make layout\n$ make package\n```\n\nA \".deb\" will be created in `./installer/linux/_out_/_pkg_/`.  You can use it to\ninstall the sample collector in `/usr/local/sample-trace2-otel-collector/*`.\nThe installer script will copy the files, register it with `systemctl(1)`,\nand start it.\n\nThe scripts in `/usr/local/sample-trace2-otel-collector/scripts/*` let you\nstop and restart the service. Use these if you want to try different settings\nin your installed `config.yml` or other YML files (such as `filter.yml`).\n\n\n### On Windows (Command Prompt)\n\nTo build a ZIP file for Windows using a Command Prompt and create BAT files.\n(_You can use either a VS Developer Command Prompt or a plain Command Prompt._)\n\n```\n\u003e go build\n\u003e cd ./installer/windows_batch_file\n\u003e build.bat\n```\n\nA ZIP file will be created in `./installer/windows_batch_file/_out_/` containing the\nexecutable, the YML files, and scripts to install and register/unregister\nthe service with Control Panel. You can redistribute the ZIP file and let\nusers (in an elevated Command Prompt) run the `install.bat` and `register.bat`\nscripts. You should then see the collector in the Control Panel Service Manager.\n\nHaving three scripts is not as nice as a stand-alone exe installer,\nbut they will let you kick the tires and/or distribute the ZIP file to your users\nwithout involving a third-party installer-builder tool.\n\n\nNOTE: The `register.bat` script will use `git config --global` to set some global\nconfig values to tell Git to send telemetry data to the collector.  These are\nper-user config values, so telemetry will only be collected from the user who\nran the script.  If you want to collect telemetry from multiple users on a\ncomputer, you should have each user execute those Git commands.  This is a\nlimitation of using \"global\" scope.  You might change it to use `--system`\nscope, but this causes problems if you have multiple versions of Git installed\non the computer, such as the one bundled with Visual Studio vs the one installed\nin `C:\\Program Files\\Git`, since each version has its own notion of where\nthe system configuration is stored. Using `--global` solves that problem.\n\n\n\n### On Windows (Git SDK) (Deprecated)\n\nIf you have the Git SDK installer and are comfortable in an `msys2 bash` shell,\nyou can create a ZIP file for Windows that uses bash scripts:\n\n```\n$ go build\n$ cd ./installer/windows_bash\n$ make layout\n$ make package\n```\n\nA ZIP file will be created in `./installers/windows_bash/_out_/` containing the\nexecutable, the YML files, and scripts to install and register/unregister\nthe service with Control Panel.  The ZIP file will contain `install.sh`,\n`register.sh` and `unregister.sh`. Run these from an elevated bash terminal.\nYou should then see the collector in the Control Panel Service Manager.\n\n_I created these scripts during development, but very few people have the Git\nSDK installed, so I created the above BAT file versions and will retire the\nbash version eventually._\n\n\n## Troubleshooting\n\n### Use the console logs\n\nOnce you have the collector running as a service, you can look at\nits console logs in `/usr/local/sample-trace2-otel-collector/logs/*`\non Linux and macOS.  On Windows, these messages are written to the\nEvent Viewer (under \"Windows Logs \u003e Application\").\n\n* NOTE I would rather that console logs on Windows were written to a\nlog file in the ProgramData directory rather than the Event Viewer, but\nthat is the behavior of the default logger built into the collector.\nIt should be possible to change this, but I have not taken time to\ninvestigate this.\n\nThere are two settings in `config.yml` to control the verbosity of\nthe console logs. You can turn them up to get more detailed messages\nand debug output. _(They will generate a lot of data, so don't forget\nto turn them back down when you're finished.)_\n\n\n### Add a real exporter\n\nIn the example `config.yml` that I included with this sample collector,\nit only writes to the console log. You'll need to add one or more (real)\nexporters to send the telemetry somewhere. The documentation in the\n`trace2receiver` component has several examples.\n\n\n### Verify the rendezvous SOCKET or PIPE\n\nThe Trace2 feature in Git will send telemetry to a SOCKET or PIPE\ndefined in the `trace2.eventtarget` system- or global-level config\nvalue. The value of this pathname must match the pathname where the\ncollector is listening.\n\nThe Git config variable is added to the Git environment using the\nvarious `service_start` or `register.sh` scripts in the installers.\n\nThe collector gets this pathname from the `config.yml` file.\n\nIf you're not seeing any data for your Git commands, verify that these\ntwo pathnames match.  It may be helpful to use `GIT_TRACE2_DST_DEBUG`\nto verify that Git can write to the SOCKET or PIPE:\n\n```\n$ git config --global trace2.eventtarget \"af_unix:/foo\"\n$ GIT_TRACE2_DST_DEBUG=1 git version\nwarning: trace2: could not connect to socket '/foo' for 'GIT_TRACE2_EVENT' tracing: No such file or directory\ngit version 2.42.0\n```\n\n\n### Too much data\n\nIf you're sending too much telemetry to your data sink or\ncloud provider, you can try the filtering built into the\n`trace2receiver` component. For example, have it drop data\nfrom uninteresting commands or repositories and let you focus\non the important commands that are causing your users pain.\n\nThe `trace2receiver` documentation has a whole section on\nsuch filtering.\n\nYou may also want to consider adding a pipeline component\n(between the trace2 receiver component and your exporter\ncomponent) that does some form of sampling. That is outside\nof the scope of my goals here.\n\n\n\n## Contributions\n\nThis project is under active development, and loves contributions from\nthe community.  Check out the [CONTRIBUTING](./CONTRIBUTING.md) guide\nfor details on getting started.\n\n\n## License\n\nThis project is licensed under the terms of the MIT open source license.\nPlease refer to [LICENSE](./LICENSE) for the full terms.\n\n\n## Maintainers\n\nSee [CODEOWNERS](./CODEOWNERS) for a list of current project maintainers.\n\n\n## Support\n\nSee [SUPPORT](./SUPPORT.md) for instructions on how to file bugs, make feature\nrequests, or seek help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ecosystem%2Fsample-trace2-otel-collector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-ecosystem%2Fsample-trace2-otel-collector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ecosystem%2Fsample-trace2-otel-collector/lists"}