Add OpenTelemetry example with Uptrace backend (#2452)

* chore: add opentelemetry example

* chore: add opentelemetry API Jupyter notebook

* chore: use a shorter title

* chore: cleanup

Co-authored-by: dvora-h <67596500+dvora-h@users.noreply.github.com>

1 files changed, 423 insertions, 0 deletions

diff --git a/docs/examples/opentelemetry_api_examples.ipynb b/docs/examples/opentelemetry_api_examples.ipynb
new file mode 100644
index 0000000..28fe758
--- /dev/null
+++ b/docs/examples/opentelemetry_api_examples.ipynb
@@ -0,0 +1,423 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7b02ea52",
+   "metadata": {},
+   "source": [
+    "# OpenTelemetry Python API"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "56520927",
+   "metadata": {},
+   "source": [
+    "## Install OpenTelemetry"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "c0ed8440",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Defaulting to user installation because normal site-packages is not writeable\n",
+      "Requirement already satisfied: opentelemetry-api in /home/vmihailenco/.local/lib/python3.10/site-packages (1.14.0)\n",
+      "Requirement already satisfied: opentelemetry-sdk in /home/vmihailenco/.local/lib/python3.10/site-packages (1.14.0)\n",
+      "Requirement already satisfied: setuptools>=16.0 in /usr/lib/python3/dist-packages (from opentelemetry-api) (59.6.0)\n",
+      "Requirement already satisfied: deprecated>=1.2.6 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-api) (1.2.13)\n",
+      "Requirement already satisfied: opentelemetry-semantic-conventions==0.35b0 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-sdk) (0.35b0)\n",
+      "Requirement already satisfied: typing-extensions>=3.7.4 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-sdk) (4.4.0)\n",
+      "Requirement already satisfied: wrapt<2,>=1.10 in /home/vmihailenco/.local/lib/python3.10/site-packages (from deprecated>=1.2.6->opentelemetry-api) (1.14.1)\n",
+      "Note: you may need to restart the kernel to use updated packages.\n"
+     ]
+    }
+   ],
+   "source": [
+    "pip install opentelemetry-api opentelemetry-sdk"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "861fa9cb",
+   "metadata": {},
+   "source": [
+    "### Configure OpenTelemetry with console exporter"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "c061b6cb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from opentelemetry import trace\n",
+    "from opentelemetry.sdk.trace import TracerProvider\n",
+    "from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter\n",
+    "\n",
+    "trace.set_tracer_provider(TracerProvider())\n",
+    "trace.get_tracer_provider().add_span_processor(\n",
+    "    BatchSpanProcessor(ConsoleSpanExporter())\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ae4a626c",
+   "metadata": {},
+   "source": [
+    "### Create a span using the tracer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "f918501b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\n",
+      "    \"name\": \"operation-name\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0xff14cec5f33afeca0d04ced2c2185b39\",\n",
+      "        \"span_id\": \"0xd06e73b03bd55b4a\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.INTERNAL\",\n",
+      "    \"parent_id\": null,\n",
+      "    \"start_time\": \"2022-12-07T13:46:11.050878Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:46:12.051944Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"UNSET\"\n",
+      "    },\n",
+      "    \"attributes\": {},\n",
+      "    \"events\": [],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "import time\n",
+    "\n",
+    "tracer = trace.get_tracer(\"app_or_package_name\", \"1.0.0\")\n",
+    "\n",
+    "# measure the timing of the operation\n",
+    "with tracer.start_as_current_span(\"operation-name\") as span:\n",
+    "    time.sleep(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ec4267aa",
+   "metadata": {},
+   "source": [
+    "### Record attributes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "fa9d265f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\n",
+      "    \"name\": \"operation-name\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0xfc11f0cc7afeefd79134eea639f5c78b\",\n",
+      "        \"span_id\": \"0xee791bf3cab65079\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.INTERNAL\",\n",
+      "    \"parent_id\": null,\n",
+      "    \"start_time\": \"2022-12-07T13:46:30.886188Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:46:31.887323Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"UNSET\"\n",
+      "    },\n",
+      "    \"attributes\": {\n",
+      "        \"enduser.id\": \"jupyter\",\n",
+      "        \"enduser.email\": \"jupyter@redis-py\"\n",
+      "    },\n",
+      "    \"events\": [],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "with tracer.start_as_current_span(\"operation-name\") as span:\n",
+    "    if span.is_recording():\n",
+    "        span.set_attribute(\"enduser.id\", \"jupyter\")\n",
+    "        span.set_attribute(\"enduser.email\", \"jupyter@redis-py\")\n",
+    "    time.sleep(1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e40655de",
+   "metadata": {},
+   "source": [
+    "### Change the span kind"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "af2980ac",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\n",
+      "    \"name\": \"operation-name\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0x2b4d1ba36423e6c17067079f044b5b62\",\n",
+      "        \"span_id\": \"0x323d6107cfe594bd\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.SERVER\",\n",
+      "    \"parent_id\": null,\n",
+      "    \"start_time\": \"2022-12-07T13:53:20.538393Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:53:20.638595Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"UNSET\"\n",
+      "    },\n",
+      "    \"attributes\": {},\n",
+      "    \"events\": [],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "with tracer.start_as_current_span(\"operation-name\", kind=trace.SpanKind.SERVER) as span:\n",
+    "    time.sleep(0.1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2a9f1d99",
+   "metadata": {},
+   "source": [
+    "### Exceptions are automatically recorded"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "1b453d66",
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "ValueError",
+     "evalue": "",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[6], line 3\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[38;5;28;01mwith\u001b[39;00m tracer\u001b[38;5;241m.\u001b[39mstart_as_current_span(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124moperation-name\u001b[39m\u001b[38;5;124m\"\u001b[39m, kind\u001b[38;5;241m=\u001b[39mtrace\u001b[38;5;241m.\u001b[39mSpanKind\u001b[38;5;241m.\u001b[39mSERVER) \u001b[38;5;28;01mas\u001b[39;00m span:\n\u001b[1;32m      2\u001b[0m     time\u001b[38;5;241m.\u001b[39msleep(\u001b[38;5;241m0.1\u001b[39m)\n\u001b[0;32m----> 3\u001b[0m     \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m\n",
+      "\u001b[0;31mValueError\u001b[0m: "
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\n",
+      "    \"name\": \"operation-name\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0x20457d98d4456b99810163027c7899de\",\n",
+      "        \"span_id\": \"0xf16e4c1620091c72\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.SERVER\",\n",
+      "    \"parent_id\": null,\n",
+      "    \"start_time\": \"2022-12-07T13:55:24.108227Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:55:24.208771Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"ERROR\",\n",
+      "        \"description\": \"ValueError: \"\n",
+      "    },\n",
+      "    \"attributes\": {},\n",
+      "    \"events\": [\n",
+      "        {\n",
+      "            \"name\": \"exception\",\n",
+      "            \"timestamp\": \"2022-12-07T13:55:24.208730Z\",\n",
+      "            \"attributes\": {\n",
+      "                \"exception.type\": \"ValueError\",\n",
+      "                \"exception.message\": \"\",\n",
+      "                \"exception.stacktrace\": \"Traceback (most recent call last):\\n  File \\\"/home/vmihailenco/.local/lib/python3.10/site-packages/opentelemetry/trace/__init__.py\\\", line 573, in use_span\\n    yield span\\n  File \\\"/home/vmihailenco/.local/lib/python3.10/site-packages/opentelemetry/sdk/trace/__init__.py\\\", line 1033, in start_as_current_span\\n    yield span_context\\n  File \\\"/tmp/ipykernel_241440/2787006841.py\\\", line 3, in <module>\\n    raise ValueError\\nValueError\\n\",\n",
+      "                \"exception.escaped\": \"False\"\n",
+      "            }\n",
+      "        }\n",
+      "    ],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "with tracer.start_as_current_span(\"operation-name\", kind=trace.SpanKind.SERVER) as span:\n",
+    "    time.sleep(0.1)\n",
+    "    raise ValueError"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23708329",
+   "metadata": {},
+   "source": [
+    "### Use nested blocks to create child spans"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "9eb261d7",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\n",
+      "    \"name\": \"child-span\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0x5625fbd0a1be15b49cda0d2bb236d158\",\n",
+      "        \"span_id\": \"0xc13b2c102566ffaf\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.INTERNAL\",\n",
+      "    \"parent_id\": \"0xa5f1a9afdf26173c\",\n",
+      "    \"start_time\": \"2022-12-07T13:57:14.011221Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:57:14.011279Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"UNSET\"\n",
+      "    },\n",
+      "    \"attributes\": {\n",
+      "        \"foo\": \"bar\"\n",
+      "    },\n",
+      "    \"events\": [],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n",
+      "{\n",
+      "    \"name\": \"operation-name\",\n",
+      "    \"context\": {\n",
+      "        \"trace_id\": \"0x5625fbd0a1be15b49cda0d2bb236d158\",\n",
+      "        \"span_id\": \"0xa5f1a9afdf26173c\",\n",
+      "        \"trace_state\": \"[]\"\n",
+      "    },\n",
+      "    \"kind\": \"SpanKind.INTERNAL\",\n",
+      "    \"parent_id\": null,\n",
+      "    \"start_time\": \"2022-12-07T13:57:13.910849Z\",\n",
+      "    \"end_time\": \"2022-12-07T13:57:14.011320Z\",\n",
+      "    \"status\": {\n",
+      "        \"status_code\": \"UNSET\"\n",
+      "    },\n",
+      "    \"attributes\": {},\n",
+      "    \"events\": [],\n",
+      "    \"links\": [],\n",
+      "    \"resource\": {\n",
+      "        \"attributes\": {\n",
+      "            \"telemetry.sdk.language\": \"python\",\n",
+      "            \"telemetry.sdk.name\": \"opentelemetry\",\n",
+      "            \"telemetry.sdk.version\": \"1.14.0\",\n",
+      "            \"service.name\": \"unknown_service\"\n",
+      "        },\n",
+      "        \"schema_url\": \"\"\n",
+      "    }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "with tracer.start_as_current_span(\"operation-name\") as span:\n",
+    "    time.sleep(0.1)\n",
+    "    with tracer.start_as_current_span(\"child-span\") as span:\n",
+    "        span.set_attribute(\"foo\", \"bar\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}