From 26c68a0f8806a8b123a7b452135e2902a5fc5038 Mon Sep 17 00:00:00 2001 From: Alberto Sartori Date: Sun, 16 Jul 2023 22:04:13 +0200 Subject: [PATCH] Opentelemetry instrumentation http (#186) * Add opentelemetry_instrumentation_http utility library * Update utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.erl Co-authored-by: Tristan Sloughter * Fix dialyzer * Update changelog --------- Co-authored-by: Tristan Sloughter --- .github/labeler.yml | 3 + .github/workflows/erlang.yml | 31 +++ .../.gitignore | 19 ++ .../CHANGELOG.md | 7 + .../LICENSE | 191 ++++++++++++++++++ .../README.md | 22 ++ .../docs.config | 4 + .../docs.sh | 15 ++ .../rebar.config | 37 ++++ .../rebar.lock | 1 + ...opentelemetry_instrumentation_http.app.src | 17 ++ .../opentelemetry_instrumentation_http.erl | 110 ++++++++++ 12 files changed, 457 insertions(+) create mode 100644 utilities/opentelemetry_instrumentation_http/.gitignore create mode 100644 utilities/opentelemetry_instrumentation_http/CHANGELOG.md create mode 100644 utilities/opentelemetry_instrumentation_http/LICENSE create mode 100644 utilities/opentelemetry_instrumentation_http/README.md create mode 100644 utilities/opentelemetry_instrumentation_http/docs.config create mode 100755 utilities/opentelemetry_instrumentation_http/docs.sh create mode 100644 utilities/opentelemetry_instrumentation_http/rebar.config create mode 100644 utilities/opentelemetry_instrumentation_http/rebar.lock create mode 100644 utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.app.src create mode 100644 utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.erl diff --git a/.github/labeler.yml b/.github/labeler.yml index e125a39..60d360a 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -82,3 +82,6 @@ opentelemetry_tesla: opentelemetry_xray: - utilities/opentelemetry_xray/**/* + +opentelemetry_instrumentation_http: + - utilities/opentelemetry_instrumentation_http/**/* diff --git a/.github/workflows/erlang.yml b/.github/workflows/erlang.yml index a1859c9..43b4992 100644 --- a/.github/workflows/erlang.yml +++ b/.github/workflows/erlang.yml @@ -118,3 +118,34 @@ jobs: run: rebar3 get-deps - name: Test run: rebar3 ct + + opentelemetry-instrumentation-http: + needs: [test-matrix] + if: (contains(github.event.pull_request.labels.*.name, 'erlang') && contains(github.event.pull_request.labels.*.name, 'opentelemetry_instrumentation_http')) + env: + app: "opentelemetry_instrumentation_http" + defaults: + run: + working-directory: utilities/${{ env.app }} + runs-on: ubuntu-20.04 + name: OpenTelemetry Instrumentation HTTP test on OTP ${{ matrix.otp_version }} with Rebar3 ${{ matrix.rebar3_version }} + strategy: + fail-fast: false + matrix: ${{ fromJson(needs.test-matrix.outputs.matrix) }} + steps: + - uses: actions/checkout@v3 + - uses: erlef/setup-beam@v1 + with: + otp-version: ${{ matrix.otp_version }} + rebar3-version: ${{ matrix.rebar3_version }} + - name: Cache + uses: actions/cache@v3 + with: + path: | + ~/_build + key: ${{ runner.os }}-build-${{ matrix.otp_version }}-${{ matrix.rebar3_version }}-v3-${{ hashFiles('**/rebar.lock') }} + - name: Fetch deps + if: steps.deps-cache.outputs.cache-hit != 'true' + run: rebar3 get-deps + - name: Test + run: rebar3 eunit diff --git a/utilities/opentelemetry_instrumentation_http/.gitignore b/utilities/opentelemetry_instrumentation_http/.gitignore new file mode 100644 index 0000000..f1c4554 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/.gitignore @@ -0,0 +1,19 @@ +.rebar3 +_* +.eunit +*.o +*.beam +*.plt +*.swp +*.swo +.erlang.cookie +ebin +log +erl_crash.dump +.rebar +logs +_build +.idea +*.iml +rebar3.crashdump +*~ diff --git a/utilities/opentelemetry_instrumentation_http/CHANGELOG.md b/utilities/opentelemetry_instrumentation_http/CHANGELOG.md new file mode 100644 index 0000000..07e2b51 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +## v0.1.0 + +### Changed + +* Expose `extract_headers_attributes/3` and `normalize_header_name/1` fucntions to extracted selected headers in an attribute map following semantic conventions diff --git a/utilities/opentelemetry_instrumentation_http/LICENSE b/utilities/opentelemetry_instrumentation_http/LICENSE new file mode 100644 index 0000000..d665b3c --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/LICENSE @@ -0,0 +1,191 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2021, Bryan Naegele . + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/utilities/opentelemetry_instrumentation_http/README.md b/utilities/opentelemetry_instrumentation_http/README.md new file mode 100644 index 0000000..a88f820 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/README.md @@ -0,0 +1,22 @@ +# opentelemetry_instrumentation_http + +[![EEF Observability WG project](https://img.shields.io/badge/EEF-Observability-black)](https://github.com/erlef/eef-observability-wg) +[![Hex.pm](https://img.shields.io/hexpm/v/opentelemetry_instrumentation_http)](https://hex.pm/packages/opentelemetry_instrumentation_http) +![Build Status](https://github.com/open-telemetry/opentelemetry-erlang-contrib/workflows/Erlang/badge.svg) + + +## Installation + +```erlang +{deps, [ + {opentelemetry_instrumentation_http, "~> 0.1"} +]} +``` +```elixir +def deps do + [ + {:opentelemetry_instrumentation_http, "~> 0.1"} + ] +end +``` + diff --git a/utilities/opentelemetry_instrumentation_http/docs.config b/utilities/opentelemetry_instrumentation_http/docs.config new file mode 100644 index 0000000..e09daa2 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/docs.config @@ -0,0 +1,4 @@ +{source_url, <<"https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/utilities/opentelemetry_instrumentation_http">>}. +{extras, [<<"LICENSE">>]}. +{main, <<"opentelemetry_instrumentation_http">>}. +{proglang, erlang}. \ No newline at end of file diff --git a/utilities/opentelemetry_instrumentation_http/docs.sh b/utilities/opentelemetry_instrumentation_http/docs.sh new file mode 100755 index 0000000..eb2b2e0 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/docs.sh @@ -0,0 +1,15 @@ +#!/bin/bash +set -e + +# Setup: +# +# mix escript.install github elixir-lang/ex_doc +# asdf install erlang 24.0.2 +# asdf local erlang 24.0.2 + +rebar3 compile +rebar3 as docs edoc +version=0.1.0 +ex_doc "opentelemetry_instrumentation_http" $version "_build/default/lib/opentelemetry_instrumentation_http/ebin" \ + --source-ref v${version} \ + --config docs.config $@ diff --git a/utilities/opentelemetry_instrumentation_http/rebar.config b/utilities/opentelemetry_instrumentation_http/rebar.config new file mode 100644 index 0000000..6e60337 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/rebar.config @@ -0,0 +1,37 @@ +{erl_opts, [debug_info]}. +{deps, []}. + +{project_plugins, [ + covertool, + erlfmt, + rebar3_hex +]}. +{profiles, [ + {docs, [ + {deps, [edown]}, + {edoc_opts, [ + {preprocess, true}, + {doclet, edoc_doclet_chunks}, + {layout, edoc_layout_chunks}, + {dir, "_build/default/lib/opentelemetry_instrumentation_http/doc"}, + {subpackages, true} + ]} + ]}, + {test, [ + {erl_opts, [nowarn_export_all]}, + {deps, []}, + {ct_opts, [{ct_hooks, [cth_surefire]}]} + ]} +]}. + +{xref_checks, [ + undefined_function_calls, + undefined_functions, + deprecated_function_calls, + deprecated_functions +]}. +{xref_ignores, []}. + +{cover_enabled, true}. +{cover_export_enabled, true}. +{covertool, [{coverdata_files, ["ct.coverdata"]}]}. diff --git a/utilities/opentelemetry_instrumentation_http/rebar.lock b/utilities/opentelemetry_instrumentation_http/rebar.lock new file mode 100644 index 0000000..57afcca --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/rebar.lock @@ -0,0 +1 @@ +[]. diff --git a/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.app.src b/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.app.src new file mode 100644 index 0000000..e16b719 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.app.src @@ -0,0 +1,17 @@ +{application, opentelemetry_instrumentation_http, [ + {description, "OpenTelemetry Instrumentation utilities for HTTP libraries"}, + {vsn, "0.1.0"}, + {registered, []}, + {applications, [ + kernel, + stdlib + ]}, + {env, []}, + {modules, []}, + {doc, "doc"}, + {licenses, ["Apache 2.0"]}, + {links, [ + {"GitHub", + "https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/utilities/opentelemetry_instrumentation_http"} + ]} +]}. diff --git a/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.erl b/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.erl new file mode 100644 index 0000000..3cb5946 --- /dev/null +++ b/utilities/opentelemetry_instrumentation_http/src/opentelemetry_instrumentation_http.erl @@ -0,0 +1,110 @@ +-module(opentelemetry_instrumentation_http). + +-ifdef(TEST). +-include_lib("eunit/include/eunit.hrl"). +-endif. + +-export([ + extract_headers_attributes/3, + normalize_header_name/1 +]). + +-spec normalize_header_name(string() | binary()) -> Result when + Result :: binary() | {error, binary(), RestData} | {incomplete, binary(), binary()}, + RestData :: unicode:latin1_chardata() | unicode:chardata() | unicode:external_chardata(). +normalize_header_name(Header) when is_binary(Header) -> + normalize_header_name(binary_to_list(Header)); +normalize_header_name(Header) when is_list(Header) -> + unicode:characters_to_binary(string:replace(string:to_lower(Header), "-", "_", all)). + +-spec extract_headers_attributes( + request | response, + Headers :: + #{binary() | string() => binary() | [binary()]} + | [{binary() | string(), binary() | [binary()]}], + HeadersToExtract :: [binary()] +) -> #{atom() => [binary()]}. +extract_headers_attributes(_Context, _Headers, []) -> + #{}; +extract_headers_attributes(Context, Headers, HeadersToExtract) when is_list(Headers) -> + lists:foldr( + fun({HeaderName, HeaderValue}, Extracted) -> + extract_if_match(Context, HeaderName, HeaderValue, Extracted, HeadersToExtract) + end, + #{}, + Headers + ); +extract_headers_attributes(Context, Headers, HeadersToExtract) when is_map(Headers) -> + maps:fold( + fun(HeaderName, HeaderValue, Extracted) -> + extract_if_match(Context, HeaderName, HeaderValue, Extracted, HeadersToExtract) + end, + #{}, + Headers + ). + +extract_if_match(Context, HeaderName, HeaderValue, Extracted, HeadersToExtract) -> + NormalizedHeaderName = normalize_header_name(HeaderName), + case lists:member(NormalizedHeaderName, HeadersToExtract) of + false -> Extracted; + true -> set_header_attribute(Context, NormalizedHeaderName, HeaderValue, Extracted) + end. + +set_header_attribute(Context, Header, Value, HeadersAttributes) when is_list(Value) -> + maps:put(attribute_name(Context, Header), Value, HeadersAttributes); +set_header_attribute(Context, Header, Value, HeadersAttributes) -> + maps:update_with( + attribute_name(Context, Header), fun(V) -> [Value | V] end, [Value], HeadersAttributes + ). + +attribute_name(request, HeaderName) -> + binary_to_atom(<<"http.request.header.", HeaderName/binary>>); +attribute_name(response, HeaderName) -> + binary_to_atom(<<"http.response.header.", HeaderName/binary>>). + +-ifdef(TEST). + +normalize_header_name_test_() -> + [ + ?_assertEqual(normalize_header_name(<<"Content-Type">>), <<"content_type">>), + ?_assertEqual(normalize_header_name("Some-Header-NAME"), <<"some_header_name">>) + ]. + +extract_headers_attributes_test_() -> + [ + ?_assertEqual(extract_headers_attributes(request, [], []), #{}), + ?_assertEqual(extract_headers_attributes(response, #{}, []), #{}), + ?_assertEqual( + extract_headers_attributes( + request, + #{ + <<"Foo">> => <<"1">>, + "Bar-Baz" => [<<"2">>, <<"3">>], + "To-Not-Extract" => <<"4">> + }, + [<<"foo">>, <<"bar_baz">>] + ), + #{ + 'http.request.header.foo' => [<<"1">>], + 'http.request.header.bar_baz' => [<<"2">>, <<"3">>] + } + ), + ?_assertEqual( + extract_headers_attributes( + response, + [ + {<<"Foo">>, <<"1">>}, + {"Bar-Baz", <<"2">>}, + {"To-Not-Extract", <<"3">>}, + {<<"foo">>, <<"4">>} + ], + [<<"foo">>, <<"bar_baz">>] + ), + #{ + 'http.response.header.foo' => [<<"1">>, <<"4">>], + 'http.response.header.bar_baz' => [<<"2">>] + } + ) + ]. + +-endif.