From b2cdca680d07dc187f8029d76ccc66190cf3fa35 Mon Sep 17 00:00:00 2001 From: hudsonhumphries Date: Fri, 29 May 2020 17:48:05 -0500 Subject: [PATCH 1/3] Open Telemetry Onboarding Resource Guide for newcomers --- ...pen-telemetry-onboarding-resource-guide.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/open-telemetry-onboarding-resource-guide.md diff --git a/docs/open-telemetry-onboarding-resource-guide.md b/docs/open-telemetry-onboarding-resource-guide.md new file mode 100644 index 0000000000..89825264b0 --- /dev/null +++ b/docs/open-telemetry-onboarding-resource-guide.md @@ -0,0 +1,45 @@ +# Open Telemetry Onboarding Resource Guide + +Hi! If you’re looking at this document, this guide will provide you the resources as a newcomer to the Open Telemetry project. This guide will help you understand the Open Telemetry Project, its components, and specifically the C++ SDK. + +### Reading Resources + +* Medium [article](https://medium.com/opentelemetry/how-to-start-contributing-to-opentelemetry-b23991ad91f4) (October 2019) on how to start contributing to the Open Telemetry project. +* Medium [article](https://medium.com/opentelemetry/opentelemetry-beyond-getting-started-5ac43cd0fe26) (January 2020) describing the overarching goals and use cases for Open Telemetry. + +### Relevant Documentation + +* Open Telemetry [Specification](https://github.com/open-telemetry/opentelemetry-specification) + * The Open Telemetry Specification describes the requirements and expectations of for all Open Telemetry implementations. + +* Read through the [Open Telemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) GitHub repository + * This repository has a lot of good information surrounding the Open Telemetry ecosystem. At the top of the **[readme](https://github.com/open-telemetry/opentelemetry-collector/blob/master/README.md)**, there are multiple links that give newcomers a good idea of what the project is about and how to get involved in it. +* Read through the Open Telemetry Python documentation for its [API](https://opentelemetry-python.readthedocs.io/en/stable/api/api.html) and [SDK](https://opentelemetry-python.readthedocs.io/en/stable/sdk/sdk.html) + * The [API](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) and [SDK](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) documentation provides a lot of information on what the classes and their functions are used for. Since there is currently minimal documentation for C++, use the Python repository’s extensive documentation to learn more about how the API and SDK work. + +### Code Examples + +* Follow the [simple trace example](https://github.com/open-telemetry/opentelemetry-cpp/pull/92) for an introduction to basic Open Telemetry functionality in C++. Currently the example can be found in [PR #94](https://github.com/open-telemetry/opentelemetry-cpp/pull/94) + +* Read through the [Java Quick-Start Guide](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) + * This shows you how the classes and functions will interact in simple and easy to digest examples. +* Take a look at this [Java SDK example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/sdk-usage) This shows a good use case of the SDK using stdout exporter. +* Take a look at the [Java Jaeger example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/jaeger) This provides a brief introduction to the Jaeger exporter, its interface, and how to interact with the service. + +### Community Resources + +* Visit the Open Telemetry Community repo for links to public meeting notes and recorded meetings from the C++ SIG. These resources highlight current priorities in the C++ project and ongoing discussions. + * Link to the [Open Telemetry Community](https://github.com/open-telemetry/community) GitHub repository. + * [C++ SIG meeting notes.](https://docs.google.com/document/d/1i1E4-_y4uJ083lCutKGDhkpi3n4_e774SBLi9hPLocw/edit) + * [Open Telemetry YouTube Channel](https://www.youtube.com/channel/UCHZDBZTIfdy94xMjMKz-_MA)(Here is the [most recent C++ meeting](https://www.youtube.com/watch?v=zuoDyXSQ68I).) +* [Active contributors](https://github.com/open-telemetry/opentelemetry-cpp/graphs/contributors) of the project. If you have any questions about the repository, these people may be able to help. + +### Interactive Resources + +* Join the [Gitter Chat](https://gitter.im/open-telemetry/opentelemetry-cpp?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) to join the conversation around the C++ project and ask contributors any questions you may have. + + +Please contribute! You’re welcome to add more information to this guide if you come across any helpful resources. See [CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/CONTRIBUTING.md) for more information. Thanks [@ankit-bhargava](https://github.com/ankit-bhargava) and [@Brandon-Kimberly](https://github.com/Brandon-Kimberly) for contributing to this resource guide. + +Last updated May 29, 2020 + From 2e4ba15430f8e4daa6e46c508274f6ba614ea202 Mon Sep 17 00:00:00 2001 From: hudsonhumphries Date: Wed, 3 Jun 2020 16:24:00 -0500 Subject: [PATCH 2/3] Moved resources and added building instructions to CONTRIBUTING.md --- CONTRIBUTING.md | 57 +++++++++++++++++++ ...pen-telemetry-onboarding-resource-guide.md | 45 --------------- 2 files changed, 57 insertions(+), 45 deletions(-) delete mode 100644 docs/open-telemetry-onboarding-resource-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3b18e248a..f1913c560b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,3 +72,60 @@ A PR is considered to be **ready to merge** when: * Urgent fixes can take exceptions as long as it has been actively communicated. Any Approver / Maintainer can merge the PR once it is **ready to merge**. + +## Build and Run Code Examples + +Note: these instructions apply to examples configured with Bazel, see example-specific documentation for other build automation tools. + +Install the latest bazel version by following the steps listed here + +Select an example of interest from the examples folder . Inside each example directory is a `BUILD` file containing instructions for Bazel. Find the binary name of your example by inspecting the contents of this `BUILD` file. + +Build the example from the root of the opentelemetry-cpp directory using Bazel. Replace `` with the identifier found in the previous step: + +```sh +bazel build //examples/: +``` + +Run the resulting executable to see telemetry from the application as it calls the instrumented library: + +```sh +bazel-bin/examples// +``` + +For instance, building and running the `simple` example can be done as follows: + +```sh +bazel build //examples/simple:example_simple +bazel-bin/examples/simple/example_simple +``` + +## Useful Resources + +Hi! If you’re looking at this document, these resources will provide you the knowledge to get started as a newcomer to the Open Telemetry project. They will help you understand the Open Telemetry Project, its components, and specifically the C++ repository. + +### Reading Resources + +* Medium [article](https://medium.com/opentelemetry/how-to-start-contributing-to-opentelemetry-b23991ad91f4) (October 2019) on how to start contributing to the Open Telemetry project. +* Medium [article](https://medium.com/opentelemetry/opentelemetry-beyond-getting-started-5ac43cd0fe26) (January 2020) describing the overarching goals and use cases for Open Telemetry. + +### Relevant Documentation + +* Open Telemetry [Specification](https://github.com/open-telemetry/opentelemetry-specification) + * The Open Telemetry Specification describes the requirements and expectations of for all Open Telemetry implementations. + +* Read through the [Open Telemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) GitHub repository + * This repository has a lot of good information surrounding the Open Telemetry ecosystem. At the top of the **[readme](https://github.com/open-telemetry/opentelemetry-collector/blob/master/README.md)**, there are multiple links that give newcomers a good idea of what the project is about and how to get involved in it. +* Read through the Open Telemetry Python documentation + * The [API](https://opentelemetry-python.readthedocs.io/en/stable/api/api.html) and [SDK](https://opentelemetry-python.readthedocs.io/en/stable/sdk/sdk.html) documentation provides a lot of information on what the classes and their functions are used for. Since there is currently minimal documentation for C++, use the Python repository’s extensive documentation to learn more about how the API and SDK work. + +### Code Examples + +* Follow the [simple trace example](https://github.com/open-telemetry/opentelemetry-cpp/pull/92) for an introduction to basic Open Telemetry functionality in C++. Currently the example can be found in [PR #94](https://github.com/open-telemetry/opentelemetry-cpp/pull/94) + +* Read through the [Java Quick-Start Guide](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) + * This shows you how the classes and functions will interact in simple and easy to digest examples. +* Take a look at this [Java SDK example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/sdk-usage) This shows a good use case of the SDK using stdout exporter. +* Take a look at the [Java Jaeger example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/jaeger) This provides a brief introduction to the Jaeger exporter, its interface, and how to interact with the service. + +Please contribute! You’re welcome to add more information if you come across any helpful resources \ No newline at end of file diff --git a/docs/open-telemetry-onboarding-resource-guide.md b/docs/open-telemetry-onboarding-resource-guide.md deleted file mode 100644 index 89825264b0..0000000000 --- a/docs/open-telemetry-onboarding-resource-guide.md +++ /dev/null @@ -1,45 +0,0 @@ -# Open Telemetry Onboarding Resource Guide - -Hi! If you’re looking at this document, this guide will provide you the resources as a newcomer to the Open Telemetry project. This guide will help you understand the Open Telemetry Project, its components, and specifically the C++ SDK. - -### Reading Resources - -* Medium [article](https://medium.com/opentelemetry/how-to-start-contributing-to-opentelemetry-b23991ad91f4) (October 2019) on how to start contributing to the Open Telemetry project. -* Medium [article](https://medium.com/opentelemetry/opentelemetry-beyond-getting-started-5ac43cd0fe26) (January 2020) describing the overarching goals and use cases for Open Telemetry. - -### Relevant Documentation - -* Open Telemetry [Specification](https://github.com/open-telemetry/opentelemetry-specification) - * The Open Telemetry Specification describes the requirements and expectations of for all Open Telemetry implementations. - -* Read through the [Open Telemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) GitHub repository - * This repository has a lot of good information surrounding the Open Telemetry ecosystem. At the top of the **[readme](https://github.com/open-telemetry/opentelemetry-collector/blob/master/README.md)**, there are multiple links that give newcomers a good idea of what the project is about and how to get involved in it. -* Read through the Open Telemetry Python documentation for its [API](https://opentelemetry-python.readthedocs.io/en/stable/api/api.html) and [SDK](https://opentelemetry-python.readthedocs.io/en/stable/sdk/sdk.html) - * The [API](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) and [SDK](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) documentation provides a lot of information on what the classes and their functions are used for. Since there is currently minimal documentation for C++, use the Python repository’s extensive documentation to learn more about how the API and SDK work. - -### Code Examples - -* Follow the [simple trace example](https://github.com/open-telemetry/opentelemetry-cpp/pull/92) for an introduction to basic Open Telemetry functionality in C++. Currently the example can be found in [PR #94](https://github.com/open-telemetry/opentelemetry-cpp/pull/94) - -* Read through the [Java Quick-Start Guide](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) - * This shows you how the classes and functions will interact in simple and easy to digest examples. -* Take a look at this [Java SDK example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/sdk-usage) This shows a good use case of the SDK using stdout exporter. -* Take a look at the [Java Jaeger example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/jaeger) This provides a brief introduction to the Jaeger exporter, its interface, and how to interact with the service. - -### Community Resources - -* Visit the Open Telemetry Community repo for links to public meeting notes and recorded meetings from the C++ SIG. These resources highlight current priorities in the C++ project and ongoing discussions. - * Link to the [Open Telemetry Community](https://github.com/open-telemetry/community) GitHub repository. - * [C++ SIG meeting notes.](https://docs.google.com/document/d/1i1E4-_y4uJ083lCutKGDhkpi3n4_e774SBLi9hPLocw/edit) - * [Open Telemetry YouTube Channel](https://www.youtube.com/channel/UCHZDBZTIfdy94xMjMKz-_MA)(Here is the [most recent C++ meeting](https://www.youtube.com/watch?v=zuoDyXSQ68I).) -* [Active contributors](https://github.com/open-telemetry/opentelemetry-cpp/graphs/contributors) of the project. If you have any questions about the repository, these people may be able to help. - -### Interactive Resources - -* Join the [Gitter Chat](https://gitter.im/open-telemetry/opentelemetry-cpp?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) to join the conversation around the C++ project and ask contributors any questions you may have. - - -Please contribute! You’re welcome to add more information to this guide if you come across any helpful resources. See [CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/master/CONTRIBUTING.md) for more information. Thanks [@ankit-bhargava](https://github.com/ankit-bhargava) and [@Brandon-Kimberly](https://github.com/Brandon-Kimberly) for contributing to this resource guide. - -Last updated May 29, 2020 - From 7d82c824978393de32d1cf636c2ab6b5d16341a2 Mon Sep 17 00:00:00 2001 From: hudsonhumphries Date: Fri, 5 Jun 2020 16:51:34 -0500 Subject: [PATCH 3/3] Moved Build Examples to Development and fixed a period --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1913c560b..daacc9e7f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,33 @@ convention](https://google.github.io/styleguide/cppguide.html#Naming). Code is formatted automatically and enforced by CI. +### Build and Run Code Examples + +Note: these instructions apply to examples configured with Bazel, see example-specific documentation for other build automation tools. + +Install the latest bazel version by following the steps listed here + +Select an example of interest from the examples folder . Inside each example directory is a `BUILD` file containing instructions for Bazel. Find the binary name of your example by inspecting the contents of this `BUILD` file. + +Build the example from the root of the opentelemetry-cpp directory using Bazel. Replace `` with the identifier found in the previous step: + +```sh +bazel build //examples/: +``` + +Run the resulting executable to see telemetry from the application as it calls the instrumented library: + +```sh +bazel-bin/examples// +``` + +For instance, building and running the `simple` example can be done as follows: + +```sh +bazel build //examples/simple:example_simple +bazel-bin/examples/simple/example_simple +``` + ## Pull Requests ### How to Send Pull Requests @@ -73,33 +100,6 @@ A PR is considered to be **ready to merge** when: Any Approver / Maintainer can merge the PR once it is **ready to merge**. -## Build and Run Code Examples - -Note: these instructions apply to examples configured with Bazel, see example-specific documentation for other build automation tools. - -Install the latest bazel version by following the steps listed here - -Select an example of interest from the examples folder . Inside each example directory is a `BUILD` file containing instructions for Bazel. Find the binary name of your example by inspecting the contents of this `BUILD` file. - -Build the example from the root of the opentelemetry-cpp directory using Bazel. Replace `` with the identifier found in the previous step: - -```sh -bazel build //examples/: -``` - -Run the resulting executable to see telemetry from the application as it calls the instrumented library: - -```sh -bazel-bin/examples// -``` - -For instance, building and running the `simple` example can be done as follows: - -```sh -bazel build //examples/simple:example_simple -bazel-bin/examples/simple/example_simple -``` - ## Useful Resources Hi! If you’re looking at this document, these resources will provide you the knowledge to get started as a newcomer to the Open Telemetry project. They will help you understand the Open Telemetry Project, its components, and specifically the C++ repository. @@ -128,4 +128,4 @@ Hi! If you’re looking at this document, these resources will provide you the k * Take a look at this [Java SDK example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/sdk-usage) This shows a good use case of the SDK using stdout exporter. * Take a look at the [Java Jaeger example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/jaeger) This provides a brief introduction to the Jaeger exporter, its interface, and how to interact with the service. -Please contribute! You’re welcome to add more information if you come across any helpful resources \ No newline at end of file +Please contribute! You’re welcome to add more information if you come across any helpful resources. \ No newline at end of file