{"title":"OpenTelemetry API","description":"OTLP/HTTP reference for logs, traces, and metrics, including authentication, encodings, compression, and response statuses.","order":400,"codeExamples":true,"askSuggestions":["How do I send gzip-compressed telemetry?","Why does the OTLP endpoint return a 415 status?","Should I use the /v1 or /otel/v1 endpoints?"],"navigation":true,"body":{"code":"var Component=(()=>{var g=Object.create;var c=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var E=Object.getPrototypeOf,S=Object.prototype.hasOwnProperty;var f=(n,e)=>()=>(e||n((e={exports:{}}).exports,e),e.exports),A=(n,e)=>{for(var o in e)c(n,o,{get:e[o],enumerable:!0})},d=(n,e,o,i)=>{if(e&&typeof e==\"object\"||typeof e==\"function\")for(let r of y(e))!S.call(n,r)&&r!==o&&c(n,r,{get:()=>e[r],enumerable:!(i=T(e,r))||i.enumerable});return n};var b=(n,e,o)=>(o=n!=null?g(E(n)):{},d(e||!n||!n.__esModule?c(o,\"default\",{value:n,enumerable:!0}):o,n)),v=n=>d(c({},\"__esModule\",{value:!0}),n);var h=f((P,l)=>{l.exports=_jsx_runtime});var x={};A(x,{default:()=>m,frontmatter:()=>O});var t=b(h()),O={title:\"OpenTelemetry API\",description:\"OTLP/HTTP reference for logs, traces, and metrics, including authentication, encodings, compression, and response statuses.\",order:400,codeExamples:!0,askSuggestions:[\"How do I send gzip-compressed telemetry?\",\"Why does the OTLP endpoint return a 415 status?\",\"Should I use the /v1 or /otel/v1 endpoints?\"]};function u(n){let e={a:\"a\",code:\"code\",h1:\"h1\",h2:\"h2\",li:\"li\",p:\"p\",pre:\"pre\",ul:\"ul\",...n.components},{DocsApiReferenceEndpoint:o,DocsApiReferenceQuickReference:i,DocsPreviewDocument:r,DocsPreviewSection:s,DocsTable:p}=e;return o||a(\"DocsApiReferenceEndpoint\",!0),i||a(\"DocsApiReferenceQuickReference\",!0),r||a(\"DocsPreviewDocument\",!0),s||a(\"DocsPreviewSection\",!0),p||a(\"DocsTable\",!0),(0,t.jsxs)(r,{anchors:\"opentelemetry-api authentication encoding-and-responses post-v1-logs post-v1-traces post-v1-metrics\",children:[(0,t.jsxs)(s,{sectionId:\"opentelemetry-api\",anchors:\"\",ancestors:\"\",index:\"0\",children:[(0,t.jsx)(e.h1,{id:\"opentelemetry-api\",children:\"OpenTelemetry API\"}),`\n`,(0,t.jsx)(i,{items:[{label:\"Base URL\",value:\"https://api.altertable.ai\"},{label:\"Protocol\",value:\"OTLP/HTTP\"},{label:\"Authentication\",value:\"HTTP Basic Auth\",to:\"#authentication\"}],links:[{label:\"Export logs\",to:\"#post-v1-logs\"},{label:\"Export traces\",to:\"#post-v1-traces\"},{label:\"Export metrics\",to:\"#post-v1-metrics\"}]}),`\n`,(0,t.jsxs)(e.p,{children:[\"Send OTLP/HTTP logs, traces, and metrics with an OpenTelemetry SDK, collector, or HTTP client. Altertable writes accepted telemetry to the environment's \",(0,t.jsx)(e.code,{children:\"opentelemetry\"}),\" catalog.\"]}),`\n`,(0,t.jsxs)(e.p,{children:[\"For setup and verification, follow \",(0,t.jsx)(e.a,{href:\"/docs/opentelemetry/setup\",children:\"Configure an exporter\"}),\". The \",(0,t.jsx)(e.a,{href:\"https://api.altertable.ai/openapi/otlp.json\",children:\"deployed OpenAPI contract\"}),\" lists the operations; the \",(0,t.jsx)(e.a,{href:\"https://opentelemetry.io/docs/specs/otlp/\",children:\"OTLP specification\"}),\" defines the signal payloads.\"]}),`\n`]}),(0,t.jsxs)(s,{sectionId:\"authentication\",anchors:\"\",ancestors:\"\",index:\"1\",children:[(0,t.jsx)(e.h2,{id:\"authentication\",children:\"Authentication\"}),`\n`,(0,t.jsxs)(e.p,{children:[\"Use HTTP Basic Auth with \",(0,t.jsx)(e.a,{href:\"/docs/administration/lakehouse-credentials\",children:\"lakehouse credentials\"}),\" from the target environment. Every request requires \",(0,t.jsx)(e.code,{children:\"Authorization: Basic <BASE64_USERNAME_COLON_PASSWORD>\"}),\". With curl, pass \",(0,t.jsx)(e.code,{children:'--user \"$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD\"'}),\" to construct the header.\"]}),`\n`,(0,t.jsx)(e.p,{children:\"Set these variables with the same environment\\u2019s lakehouse credentials before running the request examples:\"}),`\n`,(0,t.jsx)(e.pre,{children:(0,t.jsx)(e.code,{className:\"language-bash\",children:`ALTERTABLE_USERNAME='{{LAKEHOUSE_USERNAME}}'\nALTERTABLE_PASSWORD='{{LAKEHOUSE_PASSWORD}}'\n`})}),`\n`]}),(0,t.jsxs)(s,{sectionId:\"encoding-and-responses\",anchors:\"\",ancestors:\"\",index:\"2\",children:[(0,t.jsx)(e.h2,{id:\"encoding-and-responses\",children:\"Encoding and responses\"}),`\n`,(0,t.jsxs)(e.ul,{children:[`\n`,(0,t.jsxs)(e.li,{children:[\"Set \",(0,t.jsx)(e.code,{children:\"Content-Type\"}),\" to \",(0,t.jsx)(e.code,{children:\"application/x-protobuf\"}),\" for binary protobuf or \",(0,t.jsx)(e.code,{children:\"application/json\"}),\" for OTLP JSON.\"]}),`\n`,(0,t.jsxs)(e.li,{children:[\"For compressed requests, gzip the body and send \",(0,t.jsx)(e.code,{children:\"Content-Encoding: gzip\"}),\".\"]}),`\n`,(0,t.jsxs)(e.li,{children:[\"The response uses the request's encoding and the corresponding OTLP \",(0,t.jsx)(e.code,{children:\"Export*ServiceResponse\"}),\" message. A successful JSON response is currently \",(0,t.jsx)(e.code,{children:\"{}\"}),\".\"]}),`\n`,(0,t.jsxs)(e.li,{children:[\"Compatibility aliases \",(0,t.jsx)(e.code,{children:\"/otel/v1/logs\"}),\", \",(0,t.jsx)(e.code,{children:\"/otel/v1/traces\"}),\", and \",(0,t.jsx)(e.code,{children:\"/otel/v1/metrics\"}),\" use the same handlers. Prefer \",(0,t.jsx)(e.code,{children:\"/v1/*\"}),\" for new integrations.\"]}),`\n`]}),`\n`,(0,t.jsx)(p,{columns:[\"Status\",\"Meaning\"],data:[{Status:\"200\",Meaning:\"OTLP export accepted\"},{Status:\"400\",Meaning:\"Invalid protobuf, JSON, or gzip payload\"},{Status:\"401\",Meaning:\"Authentication required or credentials rejected\"},{Status:\"415\",Meaning:\"Unsupported Content-Type; use application/x-protobuf or application/json\"}]}),`\n`]}),(0,t.jsx)(s,{sectionId:\"post-v1-logs\",anchors:\"post-v1-logs\",ancestors:\"encoding-and-responses\",index:\"3\",children:(0,t.jsxs)(o,{id:\"post-v1-logs\",method:\"POST\",path:\"/v1/logs\",summary:\"Export OpenTelemetry logs.\",authentication:\"HTTP Basic Auth\",permission:\"Write telemetry\",parameters:[{name:\"Content-Type\",type:\"application/x-protobuf | application/json\",location:\"header\",required:!0,description:\"Encoding of the OTLP export request.\"},{name:\"Content-Encoding\",type:\"gzip\",location:\"header\",required:!1,description:\"Set when the body is gzip-compressed.\"},{name:\"body\",type:\"ExportLogsServiceRequest\",location:\"body\",required:!0,description:\"OTLP logs payload in protobuf or JSON encoding.\"}],requestExamples:[{language:\"curl\",code:`curl https://api.altertable.ai/v1/logs \\\\\n  --user \"$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD\" \\\\\n  -H \"Content-Type: application/x-protobuf\" \\\\\n  --data-binary @logs.pb`}],response:{status:\"200 OK (JSON request)\",language:\"json\",code:\"{}\"},children:[(0,t.jsxs)(e.p,{children:[\"Query accepted logs in \",(0,t.jsx)(e.code,{children:\"opentelemetry.main.logs\"}),\". See \",(0,t.jsx)(e.a,{href:\"/docs/opentelemetry/logs\",children:\"Send logs\"}),\" for setup and verification.\"]}),(0,t.jsxs)(e.p,{children:[\"The response is an \",(0,t.jsx)(e.code,{children:\"ExportLogsServiceResponse\"}),\", encoded as protobuf or JSON to match the request. The \",(0,t.jsx)(e.a,{href:\"#encoding-and-responses\",children:\"response statuses\"}),\" apply to this endpoint.\"]})]})}),(0,t.jsx)(s,{sectionId:\"post-v1-traces\",anchors:\"post-v1-traces\",ancestors:\"encoding-and-responses\",index:\"4\",children:(0,t.jsxs)(o,{id:\"post-v1-traces\",method:\"POST\",path:\"/v1/traces\",summary:\"Export OpenTelemetry traces.\",authentication:\"HTTP Basic Auth\",permission:\"Write telemetry\",parameters:[{name:\"Content-Type\",type:\"application/x-protobuf | application/json\",location:\"header\",required:!0,description:\"Encoding of the OTLP export request.\"},{name:\"Content-Encoding\",type:\"gzip\",location:\"header\",required:!1,description:\"Set when the body is gzip-compressed.\"},{name:\"body\",type:\"ExportTraceServiceRequest\",location:\"body\",required:!0,description:\"OTLP traces payload in protobuf or JSON encoding.\"}],requestExamples:[{language:\"curl\",code:`curl https://api.altertable.ai/v1/traces \\\\\n  --user \"$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD\" \\\\\n  -H \"Content-Type: application/x-protobuf\" \\\\\n  --data-binary @traces.pb`}],response:{status:\"200 OK (JSON request)\",language:\"json\",code:\"{}\"},children:[(0,t.jsxs)(e.p,{children:[\"Query accepted traces in \",(0,t.jsx)(e.code,{children:\"opentelemetry.main.spans\"}),\". See \",(0,t.jsx)(e.a,{href:\"/docs/opentelemetry/traces\",children:\"Send traces\"}),\" for setup and verification.\"]}),(0,t.jsxs)(e.p,{children:[\"The response is an \",(0,t.jsx)(e.code,{children:\"ExportTraceServiceResponse\"}),\", encoded as protobuf or JSON to match the request. The \",(0,t.jsx)(e.a,{href:\"#encoding-and-responses\",children:\"response statuses\"}),\" apply to this endpoint.\"]})]})}),(0,t.jsx)(s,{sectionId:\"post-v1-metrics\",anchors:\"post-v1-metrics\",ancestors:\"encoding-and-responses\",index:\"5\",children:(0,t.jsxs)(o,{id:\"post-v1-metrics\",method:\"POST\",path:\"/v1/metrics\",summary:\"Export OpenTelemetry metrics.\",authentication:\"HTTP Basic Auth\",permission:\"Write telemetry\",parameters:[{name:\"Content-Type\",type:\"application/x-protobuf | application/json\",location:\"header\",required:!0,description:\"Encoding of the OTLP export request.\"},{name:\"Content-Encoding\",type:\"gzip\",location:\"header\",required:!1,description:\"Set when the body is gzip-compressed.\"},{name:\"body\",type:\"ExportMetricsServiceRequest\",location:\"body\",required:!0,description:\"OTLP metrics payload in protobuf or JSON encoding.\"}],requestExamples:[{language:\"curl\",code:`curl https://api.altertable.ai/v1/metrics \\\\\n  --user \"$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD\" \\\\\n  -H \"Content-Type: application/x-protobuf\" \\\\\n  --data-binary @metrics.pb`},{language:\"bash\",code:`timestamp=\"$(date +%s)000000000\"\ncurl https://api.altertable.ai/v1/metrics \\\\\n  --user \"$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD\" \\\\\n  -H 'Content-Type: application/json' \\\\\n  --data-binary @- <<JSON\n{\n  \"resourceMetrics\": [{\n    \"resource\": {\"attributes\": [{\"key\": \"service.name\", \"value\": {\"stringValue\": \"checkout\"}}]},\n    \"scopeMetrics\": [{\"metrics\": [{\n      \"name\": \"checkout.queue_depth\",\n      \"unit\": \"1\",\n      \"gauge\": {\"dataPoints\": [{\"timeUnixNano\": \"$timestamp\", \"asDouble\": 42.5}]}\n    }]}]\n  }]\n}\nJSON`}],response:{status:\"200 OK (JSON request)\",language:\"json\",code:\"{}\"},children:[(0,t.jsxs)(e.p,{children:[\"Query accepted metrics in \",(0,t.jsx)(e.code,{children:\"opentelemetry.main.metrics\"}),\". This view joins the underlying \",(0,t.jsx)(e.code,{children:\"metric_points\"}),\" and \",(0,t.jsx)(e.code,{children:\"metric_series\"}),\" tables. Gauge, sum, histogram, exponential histogram, and summary points are supported. See \",(0,t.jsx)(e.a,{href:\"/docs/opentelemetry/metrics\",children:\"Send metrics\"}),\" for setup and verification.\"]}),(0,t.jsxs)(e.p,{children:[\"The response is an \",(0,t.jsx)(e.code,{children:\"ExportMetricsServiceResponse\"}),\", encoded as protobuf or JSON to match the request. The \",(0,t.jsx)(e.a,{href:\"#encoding-and-responses\",children:\"response statuses\"}),\" apply to this endpoint.\"]})]})})]})}function m(n={}){let{wrapper:e}=n.components||{};return e?(0,t.jsx)(e,{...n,children:(0,t.jsx)(u,{...n})}):u(n)}function a(n,e){throw new Error(\"Expected \"+(e?\"component\":\"object\")+\" `\"+n+\"` to be defined: you likely forgot to import, pass, or provide it.\")}return v(x);})();\n;return Component;"},"_id":"docs/api-references/opentelemetry.mdx","_raw":{"sourceFilePath":"docs/api-references/opentelemetry.mdx","sourceFileName":"opentelemetry.mdx","sourceFileDir":"docs/api-references","contentType":"mdx","flattenedPath":"docs/api-references/opentelemetry"},"type":"Docs","path":"/api-references/opentelemetry","level":2,"parent":"api-references"}