add an HTTP server example (#35)

* install .a as well as .so

* now the headers disappeared... let's try this

* I learned how to build my own library.

* so far, a traced HTTP server

* mention dd-trace-cpp in error messages

* some comments

* extend httplib to facilitate tracing

* traced HTTP server is working, but not yet complete

* clang-format

* give the hasher example CMake target a more specific name

* add a /sleep endpoint, and refactor/reformat

* provisional propagation

* simplify /sleep

* It works!

* put a proxy in front of the C++ server

* document the example server source code

* document the database service

* consider 400 an error in the span, which really I shouldn't, but it's the only way to get the error message into the trace

* convenience script for running the HTTP server example

* start the example README

* add demo to readme

* add attribution for picosha2 and cpp-httplib

* pull the next release

Author: dgoffredo

CMakeLists.txt

@@ -207,10 +207,6 @@ include_directories(${CMAKE_BINARY_DIR}/include)
 find_package(Threads REQUIRED)
 target_link_libraries(dd_trace_cpp-objects PUBLIC ${CMAKE_BINARY_DIR}/lib/libcurl.a PUBLIC Threads::Threads ${COVERAGE_LIBRARIES})
 
-# When installing, install the library and its public headers.
-install(TARGETS dd_trace_cpp-objects
-  FILE_SET public_headers)
-
 # Produce both shared and static versions of the library.
 add_library(dd_trace_cpp-shared SHARED $<TARGET_OBJECTS:dd_trace_cpp-objects>)
 set_target_properties(dd_trace_cpp-shared PROPERTIES OUTPUT_NAME "dd_trace_cpp")
@@ -222,6 +218,11 @@ set_target_properties(dd_trace_cpp-static PROPERTIES OUTPUT_NAME "dd_trace_cpp")
 add_dependencies(dd_trace_cpp-static dd_trace_cpp-objects)
 target_link_libraries(dd_trace_cpp-static dd_trace_cpp-objects)
 
+# When installing, install the static library, the shared library, and the
+# public headers.
+install(TARGETS dd_trace_cpp-static dd_trace_cpp-shared dd_trace_cpp-objects
+  FILE_SET public_headers)
+
 if(BUILD_TESTING)
   add_subdirectory(test)
 endif()

LICENSE-3rdparty.csv

@@ -1,3 +1,5 @@
 Component,Origin,License,Copyright
 vendored,nlohmann/json,MIT,Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>
-vendored,Catch2,Boost,Copyright (c) 2022 Two Blue Cubes Ltd. All rights reserved.
+vendored,Catch2,Boost,Copyright (c) 2022 Two Blue Cubes Ltd. All rights reserved.
+vendored,picosha2,MIT,Copyright (C) 2017 okdshin
+vendored,cpp-httplib,MIT,Copyright (c) 2023 Yuji Hirose. All rights reserved.

bin/http-server-example

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -e
+
+if [ "$DD_API_KEY" = '' ]; then
+    >&2 echo "The DD_API_KEY environment variable must be set to a Datadog API key."
+    exit 1
+fi
+
+REPO=$(dirname "$0")/..
+cd "$REPO"
+
+cd examples/http-server
+docker compose up --build --abort-on-container-exit

examples/hasher/CMakeLists.txt

@@ -1,3 +1,4 @@
-add_executable(example hasher.cpp)
+add_executable(hasher-example hasher.cpp)
+set_target_properties(hasher-example PROPERTIES OUTPUT_NAME example)
 
-target_link_libraries(example dd_trace_cpp-static)
+target_link_libraries(hasher-example dd_trace_cpp-static)

examples/http-server/README.md

@@ -0,0 +1,67 @@
+Example HTTP Server
+===================
+This directory contains a [docker compose][1] setup for a system consisting of
+three HTTP services and a [Datadog Agent][2].
+
+The "server" service is a note-taking app written in C++. Its source code is is
+in the [server/](server/) directory. See [server/server.cpp](server/server.cpp).
+It uses a modified version of [cpp-httplib][3] to accept and make HTTP requests.
+
+A reverse proxy sits in front of the server, and the reverse proxy is exposed to
+the host by binding to port 8000.
+
+![diagram of services](diagrams/services.svg)
+
+The note-taking app provides the following endpoints:
+
+- _GET /notes_
+    - Return `application/json` containing an array of notes, where each notes
+      is an array containing the note's creation time and body text.
+      For example, `[["2023-05-12 16:18:37","here is another note"],["2023-05-12 15:06:10","this is my note"]]`.
+- _POST /notes_
+    - Insert the request body into the database as a new note.
+- _GET /sleep?seconds=[duration]_
+    - Wait for the specified `[duration]` number of seconds before responding.
+
+The [bin/http-server-example](../../bin/http-server-example) script builds the
+three services, starts them, and begins tailing their logs. The "server" build
+uses a GitHub release of dd-trace-cpp, rather than using the current source
+tree. `bin/http-server-example` requires a Datadog API key via the `DD_API_KEY`
+environment variable.
+
+Once the services are started, requests can be made to `127.0.0.1:8000`. Traces
+will appear in the Datadog UI. The `docker compose` services have the following
+Datadog service names:
+
+| docker compose service name | Datadog service name |
+| --------------------------- | -------------------- |
+| proxy                       | dd-trace-cpp-http-server-example-proxy |
+| server                      | dd-trace-cpp-http-server-example-server |
+| database                    | dd-trace-cpp-http-server-example-database |
+
+Example Usage
+-------------
+In one command shell, run `bin/http-server-example` to bring up the services.
+
+![screenshot of command mentioned above](diagrams/docker-compose.png)
+
+Then, in another command shell, use `curl` to read and write some notes.
+
+![screenshot of curl being used](diagrams/curl.png)
+
+Finally, open the Datadog UI in a web browser and navigate to `APM > Traces`.
+Search for service names matching `dd-trace-cpp-http-server-example-*`.
+
+![screenshot of search results](diagrams/traces.png)
+
+Click one of the results to display a flame graph of the associated trace.
+
+![screenshot of flame graph](diagrams/flame-graph.png)
+
+At the top is the Node.js proxy that we called using `curl`. Below that is the
+C++ server to which the proxy forwarded our request. Below that is the
+Python database service, including a span indicating its use of SQLite.
+
+[1]: https://docs.docker.com/compose/
+[2]: https://docs.datadoghq.com/agent/
+[3]: https://github.com/yhirose/cpp-httplib

examples/http-server/database/Dockerfile

@@ -0,0 +1,9 @@
+from alpine:3.17
+
+run apk update && \
+    apk add python3 py3-pip && \
+    pip install ddtrace flask gevent
+
+copy database.py /usr/local/bin/database.py
+
+cmd ["ddtrace-run", "python", "/usr/local/bin/database.py"]

examples/http-server/database/database.py

@@ -0,0 +1,83 @@
+"""database - a thin wrapper around a sqlite3 database
+
+This is an HTTP server that exposes a SQLite 3 database via the following
+endpoints:
+
+    GET /query?sql=<sql>
+        Execute the <sql> against the database in read-only mode. Return
+        application/json containing an array of the resulting rows, where
+        each row is an array.
+
+        If an error occurs, return a text/plain description of the error.
+
+    GET /execute?sql=<sql>
+        Execute the <sql> against the database in read-write mode.
+        On success, return status 200 with an empty body.
+
+        If an error occurs, return a text/plain description of the error.
+
+The database initially contains the following table:
+
+    create table Note(
+        AddedWhen text,
+        Body text);
+"""
+
+import flask
+import gevent
+from gevent.pywsgi import WSGIServer
+import signal
+import sqlite3
+import sys
+
+DB_FILE_PATH = '/tmp/database.sqlite'
+
+app = flask.Flask(__name__)
+
+
+@app.route('/')
+def hello():
+    return "Hello, World!"
+
+
+@app.route('/query')
+def query():
+    request = flask.request
+    sql = request.args.get('sql')
+    if sql is None:
+        return ('"sql" query parameter is required.', 400)
+
+    with sqlite3.connect(f'file:{DB_FILE_PATH}?mode=ro') as db:
+        try:
+            return list(db.execute(sql))
+        except Exception as error:
+            return str(error) + '\n', 400
+
+
+@app.route('/execute')
+def execute():
+    request = flask.request
+    sql = request.args.get('sql')
+    if sql is None:
+        return ('"sql" query parameter is required.', 400)
+
+    with sqlite3.connect(DB_FILE_PATH) as db:
+        try:
+            db.execute(sql)
+            return ''
+        except Exception as error:
+            return str(error) + '\n', 400
+
+
+if __name__ == '__main__':
+    gevent.signal_handler(signal.SIGTERM, sys.exit)
+
+    with sqlite3.connect(DB_FILE_PATH) as db:
+        db.execute('''
+        create table if not exists Note(
+            AddedWhen text,
+            Body text);
+        ''')
+
+    http_server = WSGIServer(('', 80), app)
+    http_server.serve_forever()

examples/http-server/diagrams/Makefile

@@ -0,0 +1,5 @@
+.PHONY: all
+all: services.svg
+
+%.svg: %.dot Makefile
+	dot -Tsvg -o "$@" "$<"