diff --git a/README.md b/README.md new file mode 100644 index 0000000..225d3a0 --- /dev/null +++ b/README.md @@ -0,0 +1,73 @@ +# OpenTelemetry for Dancer2 + +[![Coverage Status]][coveralls] + +This is part of an ongoing attempt at implementing the OpenTelemetry +standard in Perl. The distribution in this repository implements a +plugin for the [Dancer2] web-framework, to generate and capture +telemetry data using the OpenTelemetry [API]. + +## What is OpenTelemetry? + +OpenTelemetry is an open source observability framework, providing a +general-purpose API, SDK, and related tools required for the instrumentation +of cloud-native software, frameworks, and libraries. + +OpenTelemetry provides a single set of APIs, libraries, agents, and collector +services to capture distributed traces and metrics from your application. You +can analyze them using Prometheus, Jaeger, and other observability tools. + +## How does this distribution fit in? + +This distribution allows authors of [Dancer2] applications to generate +telemetry data from their applications with minimal changes. In keeping with +the API / SDK separation described above, this plugin does not itself collect +or export this telemetry data. For that you will need to wire in the [SDK], for +which the best place to start is [that distribution's documentation][sdk]. + +## How do I get started? + +Install this distribution from CPAN: +``` +cpanm Dancer2::Plugin::OpenTelemetry +``` +or directly from the repository if you want to install a development +version (although note that only the CPAN version is recommended for +production environments): +``` +# On a local fork +cd path/to/this/repo +cpanm install . + +# Over the net +cpanm https://github.com/jjatria/dancer2-plugin-opentelemetry.git +``` + +Then, enable the plugin in your [Dancer2] application. Remember to use the +SDK to be able to use this telemetry data. + +``` perl +use Dancer2; +use OpenTelemetry::Plugin::OpenTelemetry; + +# Requests to this will automatically generate telemetry data +get '/' => sub { 'OK' }; +``` + +## How can I get involved? + +We are in the process of setting up an OpenTelemetry-Perl special interest +group (SIG). Until that is set up, you are free to [express your +interest][sig] or join us in IRC on the #io-async channel in irc.perl.org. + +## License + +This distribution is licensed under the same terms as Perl itself. See +[LICENSE] for more information. + +[dancer2]: https://metacpan.org/pod/Dancer2 +[sdk]: https://github.com/jjatria/perl-opentelemetry-sdk +[api]: https://github.com/jjatria/perl-opentelemetry +[coveralls]: https://coveralls.io/github/jjatria/dancer2-plugin-opentelemetry?branch=main +[license]: https://github.com/jjatria/dancer2-plugin-opentelemetry/blob/main/LICENSE +[sig]: https://github.com/open-telemetry/community/issues/828