From 89b09d35e42f62e6f5fac518ca14687e6b2087a9 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Tue, 20 Aug 2019 08:39:53 -0700 Subject: [PATCH] Remove work_in_progress dir --- work_in_progress/gRPC/gRPC.md | 12 - work_in_progress/opencensus/HTTP-stats.md | 118 -------- work_in_progress/opencensus/HTTP.md | 224 -------------- .../opencensus/StandardResources.md | 85 ------ work_in_progress/opencensus/gRPC-stats.md | 173 ----------- .../opencensus/http-out-test-cases.json | 274 ------------------ .../opentracing/semantic_conventions.md | 77 ----- work_in_progress/specification/README.md | 181 ------------ .../specification/encodings/BinaryEncoding.md | 146 ---------- .../encodings/CensusServerStatsEncoding.md | 47 --- .../specification/encodings/README.md | 15 - .../specification/resource/Resource.md | 143 --------- .../specification/trace/LogCorrelation.md | 55 ---- .../specification/trace/README.md | 11 - .../specification/trace/Sampling.md | 62 ---- work_in_progress/specification/trace/Span.md | 53 ---- .../specification/trace/TraceConfig.md | 41 --- work_in_progress/typedspans/README.md | 154 ---------- 18 files changed, 1871 deletions(-) delete mode 100644 work_in_progress/gRPC/gRPC.md delete mode 100644 work_in_progress/opencensus/HTTP-stats.md delete mode 100644 work_in_progress/opencensus/HTTP.md delete mode 100644 work_in_progress/opencensus/StandardResources.md delete mode 100644 work_in_progress/opencensus/gRPC-stats.md delete mode 100644 work_in_progress/opencensus/http-out-test-cases.json delete mode 100644 work_in_progress/opentracing/semantic_conventions.md delete mode 100644 work_in_progress/specification/README.md delete mode 100644 work_in_progress/specification/encodings/BinaryEncoding.md delete mode 100644 work_in_progress/specification/encodings/CensusServerStatsEncoding.md delete mode 100644 work_in_progress/specification/encodings/README.md delete mode 100644 work_in_progress/specification/resource/Resource.md delete mode 100644 work_in_progress/specification/trace/LogCorrelation.md delete mode 100644 work_in_progress/specification/trace/README.md delete mode 100644 work_in_progress/specification/trace/Sampling.md delete mode 100644 work_in_progress/specification/trace/Span.md delete mode 100644 work_in_progress/specification/trace/TraceConfig.md delete mode 100644 work_in_progress/typedspans/README.md diff --git a/work_in_progress/gRPC/gRPC.md b/work_in_progress/gRPC/gRPC.md deleted file mode 100644 index ef4d0aefc99..00000000000 --- a/work_in_progress/gRPC/gRPC.md +++ /dev/null @@ -1,12 +0,0 @@ -# gRPC - -## Propagation - -Propagation is how `SpanContext` is transmitted on the wire in an gRPC request. - -**TODO: review and close on binary protocol and metadata name** - -The propagation MUST inject a `SpanContext` as a gRPC metadata `grpc-trace-bin` -and MUST extract a `SpanContext` from the gRPC metadata. Serialization format is -configurable. The default serialization format should be used is [W3C binary -trace context](https://w3c.github.io/trace-context-binary/). diff --git a/work_in_progress/opencensus/HTTP-stats.md b/work_in_progress/opencensus/HTTP-stats.md deleted file mode 100644 index 6b3391d7eee..00000000000 --- a/work_in_progress/opencensus/HTTP-stats.md +++ /dev/null @@ -1,118 +0,0 @@ -# HTTP Stats - -Any particular library might provide only a subset of these measures/views/tags. -Check the language-specific documentation for the list of supported values. - -There is no special support for multi-part HTTP requests and responses. These are just treated as a single request. - -## Units - -As always, units are encoded according to the case-sensitive abbreviations from the [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html): - -* Latencies are measures in float64 milliseconds, denoted "ms" -* Sizes are measured in bytes, denoted "By" -* Dimensionless values have unit "1" - -Buckets for distributions in default views are as follows: - -* Size in bytes: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296 -* Latency in ms: 0, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000 - -## Client - -### Measures - -Client stats are recorded for each individual HTTP request, including for each individual redirect (followed or not). All stats are recorded after request processing (usually after the response body has been fully read). - -| Measure name | Unit | Description | -|---------------------------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| opencensus.io/http/client/sent_bytes | By | Total bytes sent in request body (not including headers). This is uncompressed bytes. | -| opencensus.io/http/client/received_bytes | By | Total bytes received in response bodies (not including headers but including error responses with bodies). Should be measured from actual bytes received and read, not the value of the Content-Length header. This is uncompressed bytes. Responses with no body should record 0 for this value. | -| opencensus.io/http/client/roundtrip_latency | ms | Time between first byte of request headers sent to last byte of response received, or terminal error | - -### Tags - -All client measures should be tagged with the following. - -| Tag name | Description | -|--------------------|----------------------------------------------------------------------------------------------------------| -| http_client_method | HTTP method, capitalized (i.e. GET, POST, PUT, DELETE, etc.) | -| http_client_path | URL path (not including query string) | -| http_client_status | HTTP status code as an integer (e.g. 200, 404, 500.), or "error" if no response status line was received | -| http_client_host | Value of the request Host header | - -`http_client_method`, `http_client_path`, `http_client_host` are set when an outgoing request -starts and are available in the context for the entire outgoing request processing. -`http_client_status` is set when an outgoing request finishes and is only available around the -stats recorded at the end of request processing. - -`http_client_path` and `http_client_host` might have high cardinality and you should be careful about using these -in views if your metrics backend cannot tolerate high-cardinality labels. - -### Default views - -The following set of views are considered minimum required to monitor client side performance: - -| View name | Measure | Aggregation | Tags | -|---------------------------------------------|---------------------------------------------|--------------|----------------------------------------| -| opencensus.io/http/client/sent_bytes | opencensus.io/http/client/sent_bytes | distribution | http_client_method, http_client_status | -| opencensus.io/http/client/received_bytes | opencensus.io/http/client/received_bytes | distribution | http_client_method, http_client_status | -| opencensus.io/http/client/roundtrip_latency | opencensus.io/http/client/roundtrip_latency | distribution | http_client_method, http_client_status | -| opencensus.io/http/client/completed_count | opencensus.io/http/client/roundtrip_latency | count | http_client_method, http_client_status | - -## Server - -Server measures are recorded at the end of request processing. - -### Measures - -Server stats are recorded for each individual HTTP request handled. They are recorded at the end of request handling. - -| Measure name | Unit | Description | -|------------------------------------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| opencensus.io/http/server/received_bytes | By | Total bytes received in request body (not including headers). This is uncompressed bytes. | -| opencensus.io/http/server/sent_bytes | By | Total bytes sent in response bodies (not including headers but including error responses with bodies). Should be measured from actual bytes received and read, not the value of the Content-Length header. This is uncompressed bytes. Responses with no body should record 0 for this value. | -| opencensus.io/http/server/server_latency | ms | Time between first byte of request headers read to last byte of response sent, or terminal error | - -### Tags - -All server metrics should be tagged with the following. - -| Tag name | Description | -|--------------------|---------------------------------------------------------------------| -| http_server_method | HTTP method, capitalized (i.e. GET, POST, PUT, DELETE, etc.) | -| http_server_path | URL path (not including query string) | -| http_server_status | HTTP server status code returned, as an integer e.g. 200, 404, 500. | -| http_server_host | Value of the request Host header | -| http_server_route | Logical route of the handler of this request | - -`http_server_method`, `http_server_path`, `http_server_host` are set when an incoming request -starts and are available in the context for the entire incoming request processing. -`http_server_status` is set when an incoming request finishes and is only available around the stats -recorded at the end of request processing. - -`http_server_path` and `http_server_host` are set by the client: you should be careful about using these -in views if your metrics backend cannot tolerate high-cardinality labels. - -`http_server_route` should always be a low cardinality string representing the logical route or handler of the -request. A reasonable interpretation of this would be the URL path pattern matched to handle the request, -or an explicitly specified function name. Defaults to the empty string if no other suitable value is -available. - -### Default views - -The following set of views are considered minimum required to monitor server side performance: - -| View name | Measure | Aggregation | Tags | -|-------------------------------------------|------------------------------------------|--------------|-----------------------------------------------------------| -| opencensus.io/http/server/received_bytes | opencensus.io/http/server/received_bytes | distribution | http_server_method, http_server_route, http_server_status | -| opencensus.io/http/server/sent_bytes | opencensus.io/http/server/sent_bytes | distribution | http_server_method, http_server_route, http_server_status | -| opencensus.io/http/server/server_latency | opencensus.io/http/server/server_latency | distribution | http_server_method, http_server_route, http_server_status | -| opencensus.io/http/server/completed_count | opencensus.io/http/server/server_latency | count | http_server_method, http_server_route, http_server_status | - -## FAQ - -### Why was the path removed from the default views? - -Path can have unbounded cardinality, which causes problems for time-series databases like Prometheus. -This is especially true of public-facing HTTP servers, where this becomes a DoS vector. \ No newline at end of file diff --git a/work_in_progress/opencensus/HTTP.md b/work_in_progress/opencensus/HTTP.md deleted file mode 100644 index d387a54d741..00000000000 --- a/work_in_progress/opencensus/HTTP.md +++ /dev/null @@ -1,224 +0,0 @@ -# HTTP Trace - -This document explains tracing of HTTP requests with OpenCensus. - -## Spans - -Implementations MUST create a span for outgoing requests at the client and a span for incoming -requests at the server. - -Span name is formatted as: - -* /$path for outgoing requests. -* /($path|$route) for incoming requests. - -If route cannot be determined, path is used to name the the span for outgoing requests. - -Port MUST be omitted if it is 80 or 443. - -Examples of span names: - -* /users -* /messages/[:id] -* /users/25f4c31d - -Outgoing requests should be a span kind of CLIENT and -incoming requests should be a span kind of SERVER. - -## Propagation - -Propagation is how SpanContext is transmitted on the wire in an HTTP request. - -Implementations MUST allow users to set their own propagation format and MUST provide an -implementation for [B3](https://github.com/openzipkin/b3-propagation/blob/master/README.md#http-encodings) -and [TraceContext](https://w3c.github.io/trace-context/) at least. - -If user doesn't set any propagation methods explicitly, TraceContext is used. - -> In a previous version of this spec, we recommended that B3 be the default. For backwards compatibility, -implementations may provide a way for users to "opt in" to the new default explicitly, to -avoid a silent change to defaults that could break existing deployments. - -The propagation method SHOULD modify a request object to insert a SpanContext or SHOULD be able -to extract a SpanContext from a request object. - -## Status - -Implementations MUST set status if HTTP request or response is not successful (e.g. not 2xx). In -redirection case, if the client doesn't have autoredirection support, request should be -considered successful. - -Set status code to UNKNOWN (2) if the reason cannot be inferred at the callsite or from the HTTP -status code. - -Don't set the status message if the reason can be inferred at the callsite of from the HTTP -status code. - -### Mapping from HTTP status codes to Trace status codes - -| HTTP code | Trace status code | -|-----------------------|------------------------| -| 0...199 | 2 (UNKNOWN) | -| 200...399 | 0 (OK) | -| 400 Bad Request | 3 (INVALID_ARGUMENT) | -| 504 Gateway Timeout | 4 (DEADLINE_EXCEEDED) | -| 404 Not Found | 5 (NOT_FOUND) | -| 403 Forbidden | 7 (PERMISSION_DENIED) | -| 401 Unauthorized* | 16 (UNAUTHENTICATED) | -| 429 Too Many Requests | 8 (RESOURCE_EXHAUSTED) | -| 501 Not Implemented | 12 (UNIMPLEMENTED) | -| 503 Unavailable | 14 (UNAVAILABLE) | - -Notes: 401 Unauthorized actually means unauthenticated according to RFC 7235, 3.1. - -The Status message should be the Reason-Phrase (RFC 2616 6.1.1) from the -response status line (if available). - -### Client errors for client HTTP calls - -There are a number of client errors when trying to access http endpoint. Here -are examples of mapping those to the OpenCensus status codes. - -| Client error | Trace status code | -|------------------------------|-----------------------| -| DNS resolution failed | 2 (UNKNOWN) | -| Request cancelled by caller | 1 (CANCELLED) | -| URL cannot be parsed | 3 (INVALID_ARGUMENT) | -| Request timed out | 1 (DEADLINE_EXCEEDED) | - -## Message events - -In the lifetime of an incoming and outgoing request, the following message events SHOULD be created: - -* A message event for the request body size if/when determined. -* A message event for the response size if/when determined. - -Implementations SHOULD create message event when body size is determined. - -``` --> [time], MessageEventTypeSent, UncompressedByteSize, CompressedByteSize -``` - -Implementations SHOULD create message event when response size is determined. - -``` --> [time], MessageEventTypeRecv, UncompressedByteSize, CompressedByteSize -``` - -## Attributes - -Implementations SHOULD set the following attributes on the client and server spans. For a server, -request represents the incoming request. For a client, request represents the outgoing request. - -All attributes are optional, but collector should make the best effort to -collect those. - -> Work in progress! Please note, that the list below only contains attributes that aren't contained in the [OpenTelemetry main spec](../../specification/data-semantic-conventions.md) (yet): - -| Attribute name | Description | Type |Example value | -|---------------------------|-----------------------------|--------|---------------------------| -| "http.host" | Request URL host | string | `example.com:779` | -| "http.path" | Request URL path. If empty - set to `/` | `/users/25f4c31d` | -| "http.user_agent" | Request user-agent. Do not inject attribute if user-agent is empty. | string | `HTTPClient/1.2` | | - - -Exporters should always export the collected attributes. Exporters should map the collected -attributes to backend's known attributes/labels. - -The following table summarizes how OpenCensus attributes maps to the -known attributes/labels on supported tracing backends. - -| OpenCensus attribute | Zipkin | Jaeger | Stackdriver Trace label | -|---------------------------|--------------------|--------------------|---------------------------| -| "http.host" | "http.host" | "http.host" | "/http/host" | -| "http.method" | "http.method" | "http.method" | "/http/method" | -| "http.path" | "http.path" | "http.path" | "/http/path" | -| "http.route" | "http.route" | "http.route" | "/http/route" | -| "http.user_agent" | "http.user_agent" | "http.user_agent" | "/http/user_agent" | -| "http.status_code" | "http.status_code" | "http.status_code" | "/http/status_code" | -| "http.url" | "http.url" | "http.url" | "/http/url" | - -References: - -- [Stackdriver Trace - label](https://cloud.google.com/trace/docs/reference/v1/rest/v1/projects.traces) -- [Jaeger/Open Tracing](https://github.com/opentracing/specification/blob/master/semantic_conventions.md) -- [Zipkin](https://github.com/openzipkin/zipkin-api/blob/master/thrift/zipkinCore.thrift) - -## Test Cases - -Test cases for outgoing http calls are in the file -[http-out-test-cases.json](http-out-test-cases.json). - -File consists of a set of test cases. Each test case represents outgoing http -call, response it receives and the resulting span properties. It looks like -this: - -``` json -{ -"name": "Name is populated as a path", -"method": "GET", -"url": "http://{host}:{port}/path/to/resource/", -"headers": { - "User-Agent": "test-user-agent" -}, -"responseCode": 200, -"spanName": "/path/to/resource/", -"spanStatus": "OK", -"spanKind": "Client", -"spanAttributes": { - "http.path": "/path/to/resource/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "200", - "http.user_agent": "test-user-agent" -} -} -``` - -Where `name` is the name of the test case. Properties `method`, `url` and -`headers` collection represents the outgoing call. The field `responseCode` -describes the response status code. - -The rest of the properties describe the span details of the resulting span - -it's name, kind, status and attributes. - -## Sampling - -There are two ways to control the `Sampler` used: -* Controlling the global default `Sampler` via [TraceConfig](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/TraceConfig.md). -* Pass a specific `Sampler` as an option to the HTTP plugin. Plugins should support setting -a sampler per HTTP request. - -Example cases where per-request sampling is useful: - -- Having different sampling policy per route -- Having different sampling policy per method -- Filtering out certain paths (e.g. health endpoints) to disable tracing -- Always sampling critical paths -- Sampling based on the custom request header or query parameter - -In the following Go example, incoming and outgoing request objects can -dynamically inspected to set a sampler. - -For outgoing requests: - -```go -type Transport struct { - // GetStartOptions allows to set start options per request. - GetStartOptions func(*http.Request) trace.StartOptions - - // ... -} -``` - -For incoming requests: - -```go -type Handler struct { - // GetStartOptions allows to set start options per request. - GetStartOptions func(*http.Request) trace.StartOptions - - // ... -} -``` diff --git a/work_in_progress/opencensus/StandardResources.md b/work_in_progress/opencensus/StandardResources.md deleted file mode 100644 index e6d85631d9a..00000000000 --- a/work_in_progress/opencensus/StandardResources.md +++ /dev/null @@ -1,85 +0,0 @@ -# Standard Resources - -This page lists the standard resource types in OpenCensus. For more details on how resources can -be combined see [this](../specification/resource/Resource.md). - -OpenCensus defines these fields. - * [Compute Unit](#compute-unit) - * [Container](#container) - * [Deployment Service](#deployment-service) - * [Kubernetes](#kubernetes) - * [Compute Instance](#compute-instance) - * [Host](#host) - * [Environment](#environment) - * [Cloud](#cloud) - -## TODOs -* Add logical compute units: Service, Task - instance running in a service. -* Add more compute units: Process, Lambda Function, AppEngine unit, etc. -* Add Device (mobile) and Web Browser. -* Decide if lower case strings only. -* Consider to add optional/required for each label and combination of labels (e.g when supplying a -k8s resource all k8s may be required). - -## Compute Unit -Resources defining a compute unit (e.g. Container, Process, Lambda Function). - -### Container -**type:** `container` - -**Description:** A container instance. This resource can be [merged](../../specification/api-resources.md#Merge) with a -deployment service resource, a compute instance resource, and an environment resource. - -| Label | Description | Example | -|---|---|---| -| container.name | Container name. | `opencenus-autoconf` | -| container.image.name | Name of the image the container was built on. | `gcr.io/opencensus/operator` | -| container.image.tag | Container image tag. | `0.1` | - -## Deployment Service -Resources defining a deployment service (e.g. Kubernetes). - -### Kubernetes -**type:** `k8s` - -**Description:** A Kubernetes resource. This resource can be [merged](../../specification/api-resources.md#Merge) with -a compute instance resource, and/or an environment resource. - -| Label | Description | Example | -|---|---|---| -| k8s.cluster.name | The name of the cluster that the pod is running in. | `opencensus-cluster` | -| k8s.namespace.name | The name of the namespace that the pod is running in. | `default` | -| k8s.pod.name | The name of the pod. | `opencensus-pod-autoconf` | - -## Compute Instance -Resources defining a computing instance (e.g. host). - -### Host -**type:** `host` - -**Description:** A host is defined as a general computing instance. This resource should be -[merged](../../specification/api-resources.md#Merge) with an environment resource. - - -| Label | Description | Example | -|---|---|---| -| host.hostname | Hostname of the host.
It contains what the `hostname` command returns on the host machine. | `opencensus-test` | -| host.id | Unique host id.
For Cloud this must be the instance_id assigned by the cloud provider | `opencensus-test` | -| host.name | Name of the host.
It may contain what `hostname` returns on Unix systems, the fully qualified, or a name specified by the user. | `opencensus-test` | -| host.type | Type of host.
For Cloud this must be the machine type.| `n1-standard-1` | - -## Environment - -Resources defining a running environment (e.g. Cloud, Data Center). - -### Cloud -**type:** `cloud` - -**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). - -| Label | Description | Example | -|---|---|---| -| cloud.provider | Name of the cloud provider.
Example values are aws, azure, gcp. | `gcp` | -| cloud.account.id | The cloud account id used to identify different entities. | `opencensus` | -| cloud.region | A specific geographical location where different entities can run | `us-central1` | -| cloud.zone | Zones are a sub set of the region connected through low-latency links.
In aws it is called availability-zone. | `us-central1-a` | diff --git a/work_in_progress/opencensus/gRPC-stats.md b/work_in_progress/opencensus/gRPC-stats.md deleted file mode 100644 index fd8104d5cf1..00000000000 --- a/work_in_progress/opencensus/gRPC-stats.md +++ /dev/null @@ -1,173 +0,0 @@ -# gRPC Stats - -Any particular library might provide only a subset of these measures/views/tags. -Check the language-specific documentation for the list of supported values. - -## Units - -As always, units are encoded according to the case-sensitive abbreviations from the [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html): - -* Latencies are measures in float64 milliseconds, denoted "ms" -* Sizes are measured in bytes, denoted "By" -* Counts of messages per RPC have unit "1" - -Buckets for distributions in default views are as follows: - -* Size in bytes: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296 -* Latency in ms: 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000 -* Counts (no unit): 0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536 - -## Terminology - -* **RPC** single call against a gRPC service, either streaming or unary. -* **message** individual message in an RPC. Streaming RPCs can have multiple messages per RPC. Unary RPCs always have only a single message per RPC. -* **status** string (all caps), e.g. CANCELLED, DEADLINE_EXCEEDED. See: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -## Client - -### Measures - -Client stats are recorded at the end of each outbound RPC. - -| Measure name | Unit | Description | -|-------------------------------------------|------|-----------------------------------------------------------------------------------------------| -| grpc.io/client/sent_messages_per_rpc | 1 | Number of messages sent in the RPC (always 1 for non-streaming RPCs). | -| grpc.io/client/sent_bytes_per_rpc | By | Total bytes sent across all request messages per RPC. | -| grpc.io/client/received_messages_per_rpc | 1 | Number of response messages received per RPC (always 1 for non-streaming RPCs). | -| grpc.io/client/received_bytes_per_rpc | By | Total bytes received across all response messages per RPC. | -| grpc.io/client/roundtrip_latency | ms | Time between first byte of request sent to last byte of response received, or terminal error. | -| grpc.io/client/server_latency | ms | Propagated from the server and should have the same value as "grpc.io/server/latency". | -| grpc.io/client/started_rpcs | 1 | The total number of client RPCs ever opened, including those that have not completed. | -| grpc.io/client/sent_messages_per_method | 1 | Total messages sent per method. | -| grpc.io/client/received_messages_per_method | 1 | Total messages received per method. | -| grpc.io/client/sent_bytes_per_method | By | Total bytes sent per method, recorded real-time as bytes are sent. | -| grpc.io/client/received_bytes_per_method | By | Total bytes received per method, recorded real-time as bytes are received. | - - -### Tags - -All client metrics should be tagged with the following. - -| Tag name | Description | -|--------------------|------------------------------------------------------------------------------------------------------------------| -| grpc_client_method | Full gRPC method name, including package, service and method, e.g. google.bigtable.v2.Bigtable/CheckAndMutateRow | -| grpc_client_status | gRPC server status code received, e.g. OK, CANCELLED, DEADLINE_EXCEEDED | - -`grpc_client_method` is set when an outgoing request starts and is available in all the recorded -metrics. -`grpc_client_status` is set when an outgoing request finishes and is only available around metrics -recorded at the end of the outgoing request. -Status codes should be stringified according to: -https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -### Default views - -The following set of views are considered minimum required to monitor client-side performance: - -| View name | Measure | Aggregation | Tags | -|-------------------------------------------|-------------------------------------------|--------------|----------------------------------------| -| grpc.io/client/sent_bytes_per_rpc | grpc.io/client/sent_bytes_per_rpc | distribution | grpc_client_method | -| grpc.io/client/received_bytes_per_rpc | grpc.io/client/received_bytes_per_rpc | distribution | grpc_client_method | -| grpc.io/client/roundtrip_latency | grpc.io/client/roundtrip_latency | distribution | grpc_client_method | -| grpc.io/client/completed_rpcs | grpc.io/client/roundtrip_latency | count | grpc_client_method, grpc_client_status | -| grpc.io/client/started_rpcs | grpc.io/client/started_rpcs | count | grpc_client_method | - -### Extra views - -The following set of views are considered useful but not mandatory to monitor client side performance: - -| View name | Measure | Aggregation | Tags | -|------------------------------------------|------------------------------------------|--------------|--------------------| -| grpc.io/client/sent_messages_per_rpc | grpc.io/client/sent_messages_per_rpc | distribution | grpc_client_method | -| grpc.io/client/received_messages_per_rpc | grpc.io/client/received_messages_per_rpc | distribution | grpc_client_method | -| grpc.io/client/server_latency | grpc.io/client/server_latency | distribution | grpc_client_method | -| grpc.io/client/sent_messages_per_method | grpc.io/client/sent_messages_per_method | count | grpc_client_method | -| grpc.io/client/received_messages_per_method | grpc.io/client/received_messages_per_method | count | grpc_client_method | -| grpc.io/client/sent_bytes_per_method | grpc.io/client/sent_bytes_per_method | sum | grpc_client_method | -| grpc.io/client/received_bytes_per_method | grpc.io/client/received_bytes_per_method | sum | grpc_client_method | - -## Server - -Server stats are recorded at the end of processing each RPC. - -| Measure name | Unit | Description | -|-------------------------------------------|------|-----------------------------------------------------------------------------------------------| -| grpc.io/server/received_messages_per_rpc | 1 | Number of messages received in each RPC. Has value 1 for non-streaming RPCs. | -| grpc.io/server/received_bytes_per_rpc | By | Total bytes received across all messages per RPC. | -| grpc.io/server/sent_messages_per_rpc | 1 | Number of messages sent in each RPC. Has value 1 for non-streaming RPCs. | -| grpc.io/server/sent_bytes_per_rpc | By | Total bytes sent in across all response messages per RPC. | -| grpc.io/server/server_latency | ms | Time between first byte of request received to last byte of response sent, or terminal error. | -| grpc.io/server/started_rpcs | 1 | The total number of server RPCs ever opened, including those that have not completed. | -| grpc.io/server/sent_messages_per_method | 1 | Total messages sent per method. | -| grpc.io/server/received_messages_per_method | 1 | Total messages received per method. | -| grpc.io/server/sent_bytes_per_method | By | Total bytes sent per method, recorded real-time as bytes are sent. | -| grpc.io/server/received_bytes_per_method | By | Total bytes received per method, recorded real-time as bytes are received. | - - -### Tags - -All server metrics should be tagged with the following. - -| Tag name | Description | -|--------------------|----------------------------------------------------------------------------------------------------------------| -| grpc_server_method | Full gRPC method name, including package, service and method, e.g. com.exampleapi.v4.BookshelfService/Checkout | -| grpc_server_status | gRPC server status code returned, e.g. OK, CANCELLED, DEADLINE_EXCEEDED | - -`grpc_server_method` is set when an incoming request starts and is available in the context for -the entire RPC call handling. - -`grpc_server_status` is set when an incoming request finishes and is only available around metrics -recorded at the end of the incoming request. -Status codes should be stringified according to: -https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -### Default views - -The following set of views are considered minimum required to monitor server side performance: - -| View name | Measure | Aggregation | Tags | -|-------------------------------------------|---------------------------------------|--------------|----------------------------------------| -| grpc.io/server/received_bytes_per_rpc | grpc.io/server/received_bytes_per_rpc | distribution | grpc_server_method | -| grpc.io/server/sent_bytes_per_rpc | grpc.io/server/sent_bytes_per_rpc | distribution | grpc_server_method | -| grpc.io/server/server_latency | grpc.io/server/server_latency | distribution | grpc_server_method | -| grpc.io/server/completed_rpcs | grpc.io/server/server_latency | count | grpc_server_method, grpc_server_status | -| grpc.io/server/started_rpcs | grpc.io/server/started_rpcs | count | grpc_server_method | - -### Extra views - -The following set of views are considered useful but not mandatory to monitor server side performance: - -| View name | Measure | Aggregation | Tag | -|------------------------------------------|------------------------------------------|--------------|--------------------| -| grpc.io/server/received_messages_per_rpc | grpc.io/server/received_messages_per_rpc | distribution | grpc_server_method | -| grpc.io/server/sent_messages_per_rpc | grpc.io/server/sent_messages_per_rpc | distribution | grpc_server_method | -| grpc.io/server/sent_messages_per_method | grpc.io/server/sent_messages_per_method | count | grpc_server_method | -| grpc.io/server/received_messages_per_method | grpc.io/server/received_messages_per_method | count | grpc_server_method | -| grpc.io/server/sent_bytes_per_method | grpc.io/server/sent_bytes_per_method | sum | grpc_server_method | -| grpc.io/server/received_bytes_per_method | grpc.io/server/received_bytes_per_method | sum | grpc_server_method | - -## FAQ - -### Why different tag name for server/client method? -This way users can configure views to correlate incoming with outgoing requests. A view example: - -| View name | Measure | Aggregation | Tag | -|-----------------------------------------|----------------------------------|--------------|----------------------------------------| -| grpc.io/client/latency_by_server_method | grpc.io/client/roundtrip_latency | distribution | grpc_client_method, grpc_server_method | - -### How is the server latency on the client recorded (grcp.io/client/server_latency)? -This is TBD, eventually a designated gRPC metadata key will be specified for this purpose. - -### Why no error counts? -Error counts can be computed on your metrics backend by totalling the different per-status values. - -### Why are ".../completed_rpcs" views defined over latency measures? -They can be defined over any measure recorded once per RPC (since it's just a count aggregation over the measure). -It would be unnecessary to use a separate "count" measure. - -### Why are "*_per_method" views not default? - -These views are useful for real-time reporting for streaming RPCs. However, for unary calls -they are not particularly useful, and data volume for these views could be huge compared to -default views. Only enable these views if you are using streaming RPCs and want real-time -metrics. \ No newline at end of file diff --git a/work_in_progress/opencensus/http-out-test-cases.json b/work_in_progress/opencensus/http-out-test-cases.json deleted file mode 100644 index 039a73eb5bc..00000000000 --- a/work_in_progress/opencensus/http-out-test-cases.json +++ /dev/null @@ -1,274 +0,0 @@ -[ - { - "name": "Successful GET call to https://example.com", - "method": "GET", - "url": "https://example.com/", - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "example.com", - "http.status_code": "200", - "http.url": "https://example.com/" - } - }, - { - "name": "Successfully POST call to https://example.com", - "method": "POST", - "url": "https://example.com/", - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "POST", - "http.host": "example.com", - "http.status_code": "200", - "http.url": "https://example.com/" - } - }, - { - "name": "Name is populated as a path", - "method": "GET", - "url": "http://{host}:{port}/path/to/resource/", - "responseCode": 200, - "spanName": "/path/to/resource/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/path/to/resource/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "200", - "http.url": "http://{host}:{port}/path/to/resource/" - } - }, - { - "name": "Call that cannot resolve DNS will be reported as error span", - "method": "GET", - "url": "https://sdlfaldfjalkdfjlkajdflkajlsdjf.sdlkjafsdjfalfadslkf.com/", - "spanName": "/", - "spanStatus": "UNKNOWN", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "sdlfaldfjalkdfjlkajdflkajlsdjf.sdlkjafsdjfalfadslkf.com", - "http.url": "https://sdlfaldfjalkdfjlkajdflkajlsdjf.sdlkjafsdjfalfadslkf.com/" - } - }, - { - "name": "Response code: 199. This test case is not possible to implement on some platforms as they don't allow to return this status code. Keeping this test case for visibility, but it actually simply a fallback into 200 test case", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 200, - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "200", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 200", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 200, - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "200", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 399", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 399, - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "399", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 400", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 400, - "spanName": "/", - "spanStatus": "INVALID_ARGUMENT", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "400", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 401", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 401, - "spanName": "/", - "spanStatus": "UNAUTHENTICATED", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "401", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 403", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 403, - "spanName": "/", - "spanStatus": "PERMISSION_DENIED", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "403", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 404", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 404, - "spanName": "/", - "spanStatus": "NOT_FOUND", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "404", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 429", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 429, - "spanName": "/", - "spanStatus": "RESOURCE_EXHAUSTED", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "429", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 501", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 501, - "spanName": "/", - "spanStatus": "UNIMPLEMENTED", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "501", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 503", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 503, - "spanName": "/", - "spanStatus": "UNAVAILABLE", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "503", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 504", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 504, - "spanName": "/", - "spanStatus": "DEADLINE_EXCEEDED", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "504", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "Response code: 600", - "method": "GET", - "url": "http://{host}:{port}/", - "responseCode": 600, - "spanName": "/", - "spanStatus": "UNKNOWN", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "600", - "http.url": "http://{host}:{port}/" - } - }, - { - "name": "User agent attribute populated", - "method": "GET", - "url": "http://{host}:{port}/", - "headers": { - "User-Agent": "test-user-agent" - }, - "responseCode": 200, - "spanName": "/", - "spanStatus": "OK", - "spanKind": "Client", - "spanAttributes": { - "http.path": "/", - "http.method": "GET", - "http.host": "{host}:{port}", - "http.status_code": "200", - "http.user_agent": "test-user-agent", - "http.url": "http://{host}:{port}/" - } - } - ] \ No newline at end of file diff --git a/work_in_progress/opentracing/semantic_conventions.md b/work_in_progress/opentracing/semantic_conventions.md deleted file mode 100644 index ddbcfdfab3d..00000000000 --- a/work_in_progress/opentracing/semantic_conventions.md +++ /dev/null @@ -1,77 +0,0 @@ -# Semantic Conventions - -The [OpenTracing Specification](https://github.com/opentracing/specification/blob/master/specification.md) describes the overarching language-neutral data model and API guidelines for OpenTracing. That data model includes the related concepts of **Span Tags** and **(structured) Log Fields**; though these terms are defined in the specification, there is no guidance there about standard Span tags or logging keys. - -Those semantic conventions are described by this document. The document is divided into two sections: first, tables listing all standard Span tags and logging keys; then guidance about how to combine these to model certain important semantic concepts. - -### Versioning - -Changes to this file affect the OpenTracing specification version. Additions should bump the minor version, and backwards-incompatible changes (or perhaps very large additions) should bump the major version. - -## Standard Span tags and log fields - -### Span tags table - -Span tags apply to **the entire Span**; as such, they apply to the entire timerange of the Span, not a particular moment with a particular timestamp: those sorts of events are best modelled as Span log fields (per the table in the next subsection of this document). - -> Work in progress! Please note, that the list below only contains attributes that aren't contained in the [OpenTelemetry main spec](../../specification/data-semantic-conventions.md) (yet): - -| Span tag name | Type | Notes and examples | -|:--------------|:-----|:-------------------| -| `message_bus.destination` | string | An address at which messages can be exchanged. E.g. A Kafka record has an associated `"topic name"` that can be extracted by the instrumented producer or consumer and stored using this tag. | -| `peer.address` | string | Remote "address", suitable for use in a networking client library. This may be a `"ip:port"`, a bare `"hostname"`, a FQDN or various connection strings | -| `peer.hostname` | string | Remote hostname. E.g., `"opentracing.io"`, `"internal.dns.name"` | -| `peer.ipv4` | string | Remote IPv4 address as a `.`-separated tuple. E.g., `"127.0.0.1"` | -| `peer.ipv6` | string | Remote IPv6 address as a string of colon-separated 4-char hex tuples. E.g., `"2001:0db8:85a3:0000:0000:8a2e:0370:7334"` | -| `peer.port` | integer | Remote port. E.g., `80` | -| `peer.service` | string | Remote service name (for some unspecified definition of `"service"`). E.g., `"elasticsearch"`, `"a_custom_microservice"`, `"memcache"` | -| `sampling.priority` | integer | If greater than 0, a hint to the Tracer to do its best to capture the trace. If 0, a hint to the trace to not-capture the trace. If absent, the Tracer should use its default sampling mechanism. | - -### Log fields table - -Every Span log has a specific timestamp (which must fall between the start and finish timestamps of the Span, inclusive) and one or more **fields**. What follows are the standard fields. - -| Span log field name | Type | Notes and examples | -|:--------------------|:--------|:-------------------| -| `error.kind` | string | The type or "kind" of an error (only for `event="error"` logs). E.g., `"Exception"`, `"OSError"` | -| `error.object` | object | For languages that support such a thing (e.g., Java, Python), the actual Throwable/Exception/Error object instance itself. E.g., A `java.lang.UnsupportedOperationException` instance, a python `exceptions.NameError` instance | -| `event` | string | A stable identifier for some notable moment in the lifetime of a Span. For instance, a mutex lock acquisition or release or the sorts of lifetime events in a browser page load described in the [Performance.timing](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming) specification. E.g., from [Zipkin](https://zipkin.io/pages/instrumenting.html#core-data-structures), `"cs"`, `"sr"`, `"ss"`, or `"cr"`. Or, more generally, `"initialized"` or `"timed out"`. For errors, `"error"` | -| `message` | string | A concise, human-readable, one-line message explaining the event. E.g., `"Could not connect to backend"`, `"Cache invalidation succeeded"` | -| `stack` | string | A stack trace in platform-conventional format; may or may not pertain to an error. E.g., `"File \"example.py\", line 7, in \\ncaller()\nFile \"example.py\", line 5, in caller\ncallee()\nFile \"example.py\", line 2, in callee\nraise Exception(\"Yikes\")\n"` | - -## Modelling special circumstances - -### RPCs - -The following Span tags combine to model RPCs: - -- `span.kind`: either `"client"` or `"server"`. It is important to provide this tag **at Span start time**, as it may affect internal ID generation. -- `peer.address`, `peer.hostname`, `peer.ipv4`, `peer.ipv6`, `peer.port`, `peer.service`: optional tags that describe the RPC peer (often in ways it cannot assess internally) - -### Message Bus - -A message bus is asynchronous, and therefore the relationship type used to link a Consumer Span and a Producer Span would be **Follows From** (see [References between Spans](https://github.com/opentracing/specification/blob/master/specification.md#references-between-spans) for more information on relationship types). - -The following Span tags combine to model message bus based communications: - -- `message_bus.destination`: as described in the table above -- `span.kind`: either `"producer"` or `"consumer"`. It is important to provide this tag **at Span start time**, as it may affect internal ID generation. -- `peer.address`, `peer.hostname`, `peer.ipv4`, `peer.ipv6`, `peer.port`, `peer.service`: optional tags that describe the message bus broker (often in ways it cannot assess internally) - -### Captured errors - -Errors may be described by OpenTracing in different ways, largely depending on the language. Some of these descriptive fields are specific to errors; others are not (e.g., the `event` or `message` fields). - -For languages where an error object encapsulates a stack trace and type information, log the following fields: - -- event=`"error"` -- error.object=`` - -For other languages, or when above is not feasible: - -- event=`"error"` -- message=`"..."` -- stack=`"..."` (optional) -- error.kind=`"..."` (optional) - -This scheme allows Tracer implementations to extract what information they need from the actual error object when it's available. diff --git a/work_in_progress/specification/README.md b/work_in_progress/specification/README.md deleted file mode 100644 index 8c72d2df411..00000000000 --- a/work_in_progress/specification/README.md +++ /dev/null @@ -1,181 +0,0 @@ -# Specification - -**Version:** 1.1 - -## Document Overview - -This is the "formal" OpenTracing semantic specification. Since OpenTracing must work across many languages, this document takes care to avoid language-specific concepts. That said, there is an understanding throughout that all languages have some concept of an "interface" which encapsulates a set of related capabilities. - -### Versioning policy - -The OpenTracing specification uses a `Major.Minor` version number but has no `.Patch` component. The major version increments when backwards-incompatible changes are made to the specification. The minor version increments for non-breaking changes like the introduction of new standard tags, log fields, or SpanContext reference types. (You can read more about the motivation for this versioning scheme at Issue [specification#2](https://github.com/opentracing/specification/issues/2#issuecomment-261740811)) - -## The OpenTracing Data Model - -... moved to [terminology.md](../../specification/overview.md) ... - -Each **Span** encapsulates the following state: - -- An operation name -- A start timestamp -- A finish timestamp -- A set of zero or more key:value **Span Tags**. The keys must be strings. The - values may be strings, bools, or numeric types. -- A set of zero or more **Span Logs**, each of which is itself a key:value map - paired with a timestamp. The keys must be strings, though the values may be - of any type. Not all OpenTracing implementations must support every value - type. -- A **SpanContext** (see below) -- [**References**](#references-between-spans) to zero or more causally-related **Spans** (via the - **SpanContext** of those related **Spans**) - -Each **SpanContext** encapsulates the following state: - -- Any OpenTracing-implementation-dependent state (for example, trace and span ids) needed to refer to a distinct **Span** across a process boundary -- **Baggage Items**, which are just key:value pairs that cross process boundaries - -### References between Spans - -OpenTelemetry doesn't support references. Links are described in -[terminology.md](../../specification/overview.md) - -> A Span may reference zero or more other **SpanContexts** that are causally related. OpenTracing presently defines two types of references: `ChildOf` and `FollowsFrom`. **Both reference types specifically model direct causal relationships between a child Span and a parent Span.** In the future, OpenTracing may also support reference types for Spans with non-causal relationships (e.g., Spans that are batched together, Spans that are stuck in the same queue, etc). -> -> **`ChildOf` references:** A Span may be the `ChildOf` a parent Span. In a `ChildOf` reference, the parent Span depends on the child Span in some capacity. All of the following would constitute `ChildOf` relationships: -> -> - A Span representing the server side of an RPC may be the `ChildOf` a Span representing the client side of that RPC ->- A Span representing a SQL insert may be the `ChildOf` a Span representing an ORM save method ->- Many Spans doing concurrent (perhaps distributed) work may all individually be the `ChildOf` a single parent Span that merges the results for all children that return within a deadline -> ->These could all be valid timing diagrams for children that are the `ChildOf` a parent. -> ->~~~ -> [-Parent Span---------] -> [-Child Span----] -> -> [-Parent Span--------------] -> [-Child Span A----] -> [-Child Span B----] -> [-Child Span C----] -> [-Child Span D---------------] -> [-Child Span E----] ->~~~ -> ->**`FollowsFrom` references:** Some parent Spans do not depend in any way on the result of their child Spans. In these cases, we say merely that the child Span `FollowsFrom` the parent Span in a causal sense. There are many distinct `FollowsFrom` reference sub-categories, and in future versions of OpenTracing they may be distinguished more formally. -> ->These can all be valid timing diagrams for children that "FollowFrom" a parent. -> ->~~~ -> [-Parent Span-] [-Child Span-] -> -> -> [-Parent Span--] -> [-Child Span-] -> -> -> [-Parent Span-] -> [-Child Span-] ->~~~ -> - -## The OpenTracing API - -There are three critical and inter-related types in the OpenTracing specification: `Tracer`, `Span`, and `SpanContext`. Below, we go through the behaviors of each type; roughly speaking, each behavior becomes a "method" in a typical programming language, though it may actually be a set of related sibling methods due to type overloading and so on. - -When we discuss "optional" parameters, it is understood that different languages have different ways to construe such concepts. For example, in Go we might use the "functional Options" idiom, whereas in Java we might use a builder pattern. - -### `Tracer` - -The `Tracer` interface creates `Span`s and understands how to `Inject` -(serialize) and `Extract` (deserialize) them across process boundaries. -Formally, it has the following capabilities: - -#### Start a new `Span` - -Required parameters - -- An **operation name**, a human-readable string which concisely represents the work done by the Span (for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation). The operation name should be **the most general string that identifies a (statistically) interesting class of `Span` instances**. That is, `"get_user"` is better than `"get_user/314159"`. - -For example, here are potential **operation names** for a `Span` that gets hypothetical account information: - -| Operation Name | Guidance | -|:---------------|:--------| -| `get` | Too general | -| `get_account/792` | Too specific | -| `get_account` | Good, and `account_id=792` would make a nice **`Span` tag** | - -Optional parameters - -- Zero or more **references** to related `SpanContext`s, including a shorthand for `ChildOf` and `FollowsFrom` reference types if possible. -- An optional explicit **start timestamp**; if omitted, the current walltime is used by default -- Zero or more **tags** - -**Returns** a `Span` instance that's already started (but not `Finish`ed) - -#### Inject a `SpanContext` into a carrier - -Required parameters - -- A **`SpanContext`** instance -- A **format** descriptor (typically but not necessarily a string constant) which tells the `Tracer` implementation how to encode the `SpanContext` in the carrier parameter -- A **carrier**, whose type is dictated by the **format**. The `Tracer` implementation will encode the `SpanContext` in this carrier object according to the **format**. - -#### Extract a `SpanContext` from a carrier - -Required parameters - -- A **format** descriptor (typically but not necessarily a string constant) which tells the `Tracer` implementation how to decode `SpanContext` from the carrier parameter -- A **carrier**, whose type is dictated by the **format**. The `Tracer` implementation will decode the `SpanContext` from this carrier object according to **format**. - -**Returns** a `SpanContext` instance suitable for use as a **reference** when starting a new `Span` via the `Tracer`. - -#### Note: required **format**s for injection and extraction - -Both injection and extraction rely on an extensible **format** parameter that dictates the type of the associated "carrier" as well as how a `SpanContext` is encoded in that carrier. All of the following **format**s must be supported by all Tracer implementations. - -- **Text Map**: an arbitrary string-to-string map with an unrestricted character set for both keys and values -- **HTTP Headers**: a string-to-string map with keys and values that are suitable for use in HTTP headers (a la [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.4)). In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. -- **Binary**: a (single) arbitrary binary blob representing a `SpanContext` - -### `Span` - -... moved to [specs](../../specification/api-tracing.md)... - -#### Set a **baggage** item - -Baggage items are key:value string pairs that apply to the given `Span`, its `SpanContext`, and **all `Spans` which directly or transitively _reference_ the local `Span`.** That is, baggage items propagate in-band along with the trace itself. - -Baggage items enable powerful functionality given a full-stack OpenTracing integration (for example, arbitrary application data from a mobile app can make it, transparently, all the way into the depths of a storage system), and with it some powerful costs: use this feature with care. - -Use this feature thoughtfully and with care. Every key and value is copied into every local *and remote* child of the associated Span, and that can add up to a lot of network and cpu overhead. - -Required parameters - -- The **baggage key**, a string -- The **baggage value**, a string - -#### Get a **baggage** item - -Required parameters - -- The **baggage key**, a string - -**Returns** either the corresponding **baggage value**, or some indication that such a value was missing. - -### `SpanContext` - -The `SpanContext` is more of a "concept" than a useful piece of functionality at the generic OpenTracing layer. That said, it is of critical importance to OpenTracing *implementations* and does present a thin API of its own. Most OpenTracing users only interact with `SpanContext` via [**references**](#references-between-spans) when starting new `Span`s, or when injecting/extracting a trace to/from some transport protocol. - -In OpenTracing we force `SpanContext` instances to be **immutable** in order to avoid complicated lifetime issues around `Span` finish and references. - -#### Iterate through all baggage items - -This is modeled in different ways depending on the language, but semantically the caller should be able to efficiently iterate through all baggage items in one pass given a `SpanContext` instance. - -### `NoopTracer` - -All OpenTracing language APIs must also provide some sort of `NoopTracer` implementation which can be used to flag-control OpenTracing or inject something harmless for tests (et cetera). In some cases (for example, Java) the `NoopTracer` may be in its own packaging artifact. - -### Optional API Elements - -Some languages also provide utilities to pass an active `Span` and/or `SpanContext` around a single process. For instance, `opentracing-go` provides helpers to set and get the active `Span` in Go's `context.Context` mechanism. diff --git a/work_in_progress/specification/encodings/BinaryEncoding.md b/work_in_progress/specification/encodings/BinaryEncoding.md deleted file mode 100644 index cc96489f3eb..00000000000 --- a/work_in_progress/specification/encodings/BinaryEncoding.md +++ /dev/null @@ -1,146 +0,0 @@ -# BINARY FORMAT - -The binary format can be used to encode different data types, each with different fields. This -document first describes the general format and then applies it to specific data types, -including Trace Context and Tag Context. - -## General Format -Each encoding will have a 1 byte version followed by the version format encoding: - -`` - -This will allow us to, in 1 deprecation cycle to completely switch to a new format if needed. - -## Version Format (version_id = 0) -The version format for the version_id = 0 is based on ideas from proto encoding. The main -requirements are to allow adding and removing fields in less than 1 deprecation cycle. It -contains a list of fields: - -`...` - -### Field -Each field is a 1-byte field ID paired with a field value, where the format of the field value is -determined by both the field ID and the data type. For example, field 0 in `Trace Context` may -have a completely different format than field 0 in `Tag Context` or field 1 in `Trace Context`. - -Each field that we send on the wire will have the following format: - -`` - -* `field_id` is a single byte. - -* `field_format` must be defined for each field separately. - -The specification for a data type's format must also specify whether each field is optional or -repeated. For example, `Trace-id` in `Trace Context` is optional, and `Tag` in `Tag Context` -is repeated. The specification for a data type's format MAY define a default value for any -optional field, which must be used when the field is missing. - -The specification for a data type can define versions within a version of the format, called data -type version, where each data type version adds new fields. The data type version can be useful -for describing what fields an implementation supports, but it is not included in the -serialized data. - -### Serialization Rules -Fields MUST be serialized in data type version order (i.e. all fields from version (i) of a data -type must precede all fields from version (i+1)). That is because each field has its own format, -and old implementations may not be able to determine where newer field values end. This ordering -allows old decoders to ignore any new fields when they do not know the format for those fields. -Fields within a data type version can be serialized in any order, and fields with the same field -ID do not need to be serialized consecutively. - -### Deserialization Rules -Because all the fields will be decoded in data type version order, the deserialization will -simply read the encoded input until the end of the input or until the first unknown field_id. An -unknown field id should not be considered a parse error. Implementations MAY pass on any fields -that they cannot decode, when possible (by passing-through the whole opaque tail of bytes -starting with the first field id that the current binary does not understand). - -### How can we add new fields? -If we follow the rules that we always append the new ids at the end of the buffer we can add up -to 127. - -TODO(bdrutu): Decide what to do after 127: a) use varint encoding or b) just reserve 255 as a -continuation byte. - -### How can we remove a field? -We can stop sending any field at any moment and the decoders will be able to skip the missing ids -and use the default values. - -### Trace Context - -#### Fields added in Trace Context version 0 - -##### Trace-id - -* optional -* `field_id` = 0 -* `len` = 16 - -Is the ID of the whole trace forest. It is represented as an opaque 16-bytes array, -e.g. (in hex), `4bf92f3577b34da6a3ce929d000e4736`. All bytes 0 is considered invalid. - -##### Span-id - -* optional -* `field_id` = 1 -* `len` = 8 - -Is the ID of the caller span (parent). It is represented as an opaque 8-bytes array, -e.g. (in hex), `34f067aa0ba902b7`. All bytes 0 is considered invalid. - -##### Trace-options - -* optional -* `field_id` = 2 -* `len` = 1 - -Controls tracing options such as sampling, trace level etc. It is a 1-byte -representing a 8-bit unsigned integer. The least significant bit provides -recommendation whether the request should be traced or not (1 recommends the -request should be traced, 0 means the caller does not make a decision to trace -and the decision might be deferred). The flags are recommendations given by the -caller rather than strict rules to follow for 3 reasons: - -1. Trust and abuse. -2. Bug in caller -3. Different load between caller service and callee service might force callee to down sample. - -The behavior of other bits is currently undefined. - -#### Valid example -{0, -0, 75, 249, 47, 53, 119, 179, 77, 166, 163, 206, 146, 157, 0, 14, 71, 54, -1, 52, 240, 103, 170, 11, 169, 2, 183, -2, 1} - -This corresponds to: -* `traceId` = {75, 249, 47, 53, 119, 179, 77, 166, 163, 206, 146, 157, 0, 14, 71, 54} -* `spanId` = {52, 240, 103, 170, 11, 169, 2, 183} -* `traceOptions` = 1 - -### Tag Context -The Tag Context format uses Varint encoding, which is described in -https://developers.google.com/protocol-buffers/docs/encoding#varints. - -#### Fields added in Tag Context version 0 - -##### Tag - -* repeated -* `field_id` = 0 -* `field_format` = `` where - - * `tag_key_len` is a varint encoded integer. - * `tag_key` is `tag_key_len` bytes comprising the tag key name. - * `tag_val_len` is a varint encoded integer. - * `tag_val` is `tag_val_len` bytes comprising the tag value. -* Tags can be serialized in any order. -* Multiple tag fields can contain the same tag key. All but the last value for - that key should be ignored. -* The - [size limit for serialized Tag Contexts](https://github.com/census-instrumentation/opencensus-specs/blob/master/tags/TagMap.md#limits) - should apply to all tag fields, even if some of them have duplicate keys. For - example, a serialized tag context with 10,000 small tags that all have the - same key should be considered too large. - diff --git a/work_in_progress/specification/encodings/CensusServerStatsEncoding.md b/work_in_progress/specification/encodings/CensusServerStatsEncoding.md deleted file mode 100644 index fe917887ef4..00000000000 --- a/work_in_progress/specification/encodings/CensusServerStatsEncoding.md +++ /dev/null @@ -1,47 +0,0 @@ -### Census Server Stats - -The encoding is based on [BinaryEncoding](BinaryEncoding.md) - -#### Fields added in Census Server Stats version 0 - -##### LB-Latency-Ns - -* optional -* `field_id` = 0 -* `len` = 8 - -Request processing latency observed on Load Balance. The unit is nanoseconds. -It is int64 little endian. - -##### Server-Latency_Ns - -* optional -* `field_id` = 1 -* `len` = 8 - -Request processing latency observed on Server. The unit is nanoseconds. -It is int64 little endian. - -##### Trace-Options - -* optional -* `field_id` = 2 -* `len` = 1 - -It is a 1-byte representing a 8-bit unsigned integer. The least significant -bit provides if the request was sampled on the server or not (1= sampled, -0= not sampled). - -The behavior of other bits is currently undefined. - -#### Valid example (Hex) -{`0,` - `0, 38, C7, 0, 0, 0, 0, 0, 0,` - `1, 50, C3, 0, 0, 0, 0, 0, 0,` - `2, 1`} - -This corresponds to: -* `lb_latency_ns` = 51000 (0x000000000000C738) -* `server_latency_ns` = 50000 (0x000000000000C350) -* `trace_options` = 1 (0x01) - diff --git a/work_in_progress/specification/encodings/README.md b/work_in_progress/specification/encodings/README.md deleted file mode 100644 index c760649c83f..00000000000 --- a/work_in_progress/specification/encodings/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# OpenCensus Library Encoding Package -This documentation serves to document the on-the-wire encoding format supported in -OpenCensus. It describes the key types and the overall behavior. - -## Formats -* [Binary Encoding](BinaryEncoding.md) - * [TraceContext Binary Encoding](BinaryEncoding.md#trace-context) - * [TagContext Binary Encoding](BinaryEncoding.md#tag-context) - * [Census Server Stats Encoding](CensusServerStatsEncoding.md) - -* HTTP Encoding - * [W3C TraceContext](https://github.com/TraceContext/tracecontext-spec) - * [W3C Correlation Context](https://github.com/w3c/correlation-context) - * [Stackdriver TraceContext Header](https://cloud.google.com/trace/docs/support) - * [B3 TraceContext Header](https://github.com/openzipkin/b3-propagation) diff --git a/work_in_progress/specification/resource/Resource.md b/work_in_progress/specification/resource/Resource.md deleted file mode 100644 index 9040b984a9e..00000000000 --- a/work_in_progress/specification/resource/Resource.md +++ /dev/null @@ -1,143 +0,0 @@ -# Resource API Overview -The resource library primarily defines a type that captures information about the entity -for which metrics or traces are reported. It further provides a framework for detection of -resource information from the environment and progressive population as signals propagate -from the core instrumentation library to a backend's exporter. - -## Resource type -A `Resource` describes the entity for which a signal was collected through two fields: -* `type`: an optional string which describes a well-known type of resource. -* `labels`: a dictionary of labels with string keys and values that provide information -about the entity. - -Type, label keys, and label values MUST contain only printable ASCII (codes between 32 -and 126, inclusive) and not exceed 256 characters. -Type and label keys MUST have a length greater than zero. Label keys SHOULD start with the type -and separate hierarchies with `.` characters, e.g. `k8s.namespace.name`. - -Implementations MAY define a `Resource` data type, constructed from the parameters above. -`Resource` MUST have getters for retrieving all the information used in `Resource` definition. - -Example in Go: -```go -type Resource { - Type string - Labels map[string]string -} -``` - -For the proto definition see [here][resource-proto-link] - -## Populating resources -Resource information MAY be populated at any point between startup of the instrumented -application and passing it to a backend-specific exporter. This explicitly includes -the path through future OpenCensus components such as agents or services. - -For example, process-identifying information may be populated through the library while -an agent attaches further labels about the underlying VM, the cluster, or geo-location. - -### From environment variables -Population of resource information from environment variables MUST be provided by the -core library. It provides the user with an ubiquitous way to manually provide information -that may not be detectable automatically through available integration libraries. - -Two environment variables are used: -* `OC_RESOURCE_TYPE`: defines the resource type. Leading and trailing whitespaces are trimmed. -* `OC_RESOURCE_LABELS`: defines resource labels as a comma-separated list of key/value pairs -(`[ ="value" [ ,="" ... ] ]`). `"` characters in values MUST be escaped with `\`. - -For example: -* `OC_RESOURCE_TYPE=container` -* `OC_RESOURCE_LABELS=container.name="c1",k8s.pod.name="pod-xyz-123",k8s.namespace.name="default"` - -Population from environment variables MUST be the first applied detection process unless -the user explicitly overwrites this behavior. - -### Auto-detection -Auto-detection of resource information in specific environments, e.g. specific cloud -vendors, MUST be implemented outside of the core libraries in third party or -[census-ecosystem][census-ecosystem] repositories. - -### Detectors -To make auto-detection implementations easy to use, the core resource package SHOULD define -an interface to retrieve resource information. Additionally, helper functionality MAY be -provided to effectively make use of this interface. -The exact shape of those interfaces and helpers SHOULD be idiomatic to the respective language. - -Example in Go: - -```go -type Detector func(context.Context) (*Resource, error) - -// Returns a detector that runs all input detectors sequentially and merges their results. -func ChainedDetector(...Detector) Detector -``` - -### Updates -OpenCensus's resource representation is focused on providing static, uniquely identifying -information and thus those mutable attributes SHOULD NOT be included in the resource -representation. -Resource type and labels MUST NOT be mutated after initialization. Any changes MUST be -effectively be treated as a different resource and any associated signal state MUST be reset. - -## Exporter translation -A resource object MUST NOT be mutated further once it is passed to a backend-specific exporter. -From the provided resource information, the exporter MAY transform, drop, or add information -to build the resource identifying data type specific to its backend. -If the passed resource does not contain sufficient information, an exporter MAY drop -signal data entirely, if no sufficient resource information is provided to perform a correct -write. - -For example, from a resource object - -```javascript -{ - "type": "container", - "labels": { - // Populated from VM environment through auto-detection library. - "host.id": "instance1", - "cloud.zone": "eu-west2-a", - "cloud.account.id": "project1", - // Populated through OpenCensus resource environment variables. - "k8s.cluster_name": "cluster1", - "k8s.namespace.name": "ns1", - "k8s.pod.name": "pod1", - "container.name": "container1", - }, -} -``` - -an exporter for Stackdriver would create the following "monitored resource", which is a -resource type with well-known identifiers specific to its API: - -```javascript -{ - "type": "k8s_container", - "labels": { - "project_id": "project1", - "location": "eu-west2-a", - "cluster_name": "cluster1", - "namespace_name": "ns1", - "pod_name": "pod1", - "container_name": "container1", - }, -} -``` - -For another, hypothetical, backend a simple unique identifier might be constructed instead -by its exporter: - -``` -cluster1/ns1/pod1/container1 -``` - -Exporter libraries MAY provide a default translation for well-known input resource types and labels. -Those would generally be based on community-supported detection integrations maintained in the -[census-ecosystem][census-ecosystem-link] organisation. - -Additionally, exporters SHOULD provide configuration hooks for users to provide their own -translation unless the exporter's backend does not support resources at all. For such backends, -exporters SHOULD allow attaching converting resource labels to metric tags. - -[census-ecosystem-link]: https://github.com/census-ecosystem -[resource-proto-link]: https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/resource/v1/resource.proto diff --git a/work_in_progress/specification/trace/LogCorrelation.md b/work_in_progress/specification/trace/LogCorrelation.md deleted file mode 100644 index 3e893ba1a3d..00000000000 --- a/work_in_progress/specification/trace/LogCorrelation.md +++ /dev/null @@ -1,55 +0,0 @@ -# Log Correlation - -Log correlation is a feature that inserts information about the current span into log entries -created by existing logging frameworks. The feature can be used to add more context to log entries, -filter log entries by trace ID, or find log entries associated with a specific trace or span. - -The design of a log correlation implementation depends heavily on the details of the particular -logging framework that it supports. Therefore, this document only covers the aspects of log -correlation that could be shared across log correlation implementations for multiple languages and -logging frameworks. It doesn't cover how to hook into the logging framework. - -## Identifying the span to associate with a log entry - -A log correlation implementation should look up tracing data from the span that is current at the -point of the log statement. See -[Span.md#how-span-interacts-with-context](Span.md#how-span-interacts-with-context) for the -definition of the current span. - -## Tracing data to include in log entries - -A log correlation implementation should make the following pieces of tracing data from the current -span context available in each log entry: - -### Trace ID - -The trace ID of the current span. See [SpanContext](../overview.md#spancontext). - -### Span ID - -The span ID of the current span. See [SpanContext](../overview.md#spancontext). - -### Sampling Decision - -The sampling bit of the current span, as a boolean. See -[SpanContext](../overview.md#spancontext). - -TODO(sebright): Include "samplingScore" once that field is added to the SpanContext. - -TODO(sebright): Add a section on fields from the Tracestate. Users should be able to add -vendor-specific fields from the Tracestate to logs, using a callback mechanism. - -TODO(sebright): Consider adding parent span ID, to allow recreating the trace structure from logs. - -## String format for tracing data - -The logging framework may require the pieces of tracing data to be converted to strings. In that -case, the log correlation implementation should format the trace ID and span ID as lowercase base 16 -and format the sampling decision as "true" or "false". - -## Key names for tracing data - -Some logging frameworks allow the insertion of arbitrary key-value pairs into log entries. When -a log correlation implementation inserts tracing data by that method, the key names should be -"traceId", "spanId", and "traceSampled" by default. The log correlation implementation may allow -the user to override the key names. diff --git a/work_in_progress/specification/trace/README.md b/work_in_progress/specification/trace/README.md deleted file mode 100644 index 7b52c537db2..00000000000 --- a/work_in_progress/specification/trace/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# OpenCensus Library Trace Package - -## Main APIs -* [Span](Span.md) -* [TraceConfig](TraceConfig.md) - -## Utils -* [gRPC integration](../../gRPC/gRPC.md): document about how to instrument gRPC framework. -* [HTTP integration](../../opencensus/HTTP.md): document about how to instrument http frameworks. -* [Sampling logic](Sampling.md): document about how sampling works. -* [Log correlation](LogCorrelation.md): specification for a feature for inserting tracing data into log entries. diff --git a/work_in_progress/specification/trace/Sampling.md b/work_in_progress/specification/trace/Sampling.md deleted file mode 100644 index 363e13f245a..00000000000 --- a/work_in_progress/specification/trace/Sampling.md +++ /dev/null @@ -1,62 +0,0 @@ -# Sampling - -This document is about the sampling bit, sampling decision, samplers and how and when -OpenCensus samples traces. A sampled trace is one that gets exported via the configured -exporters. - -## Sampling Bit (propagated via TraceOptions) - -The Sampling bit is always set only at the start of a Span, using a `Sampler` - -### What kind of samplers does OpenCensus support? -* `AlwaysSample` - sampler that makes a "yes" decision every time. -* `NeverSample` - sampler that makes a "no" decision every time. -* `Probability` - sampler that tries to uniformly sample traces with a given probability. When -applied to a child `Span` of a **sampled** parent `Span`, the child `Span` keeps the sampling -decision. -* `RateLimiting` - sampler that tries to sample with a rate per time window (0.1 traces/second). -When applied to a child `Span` of a **sampled** parent `Span`, the child `Span` keeps the sampling -decision. For implementation details see [this](#ratelimiting-sampler-implementation-details) - -### How can users control the Sampler that is used for sampling? -There are 2 ways to control the `Sampler` used when the library samples: -* Controlling the global default `Sampler` via [TraceConfig](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/TraceConfig.md). -* Pass a specific `Sampler` when starting the [Span](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Span.md) -(a.k.a. "span-scoped"). - * For example `AlwaysSample` and `NeverSample` can be used to implement request-specific - decisions such as those based on http paths. - -### When does OpenCensus sample traces? -The OpenCensus library samples based on the following rules: -1. If the span is a root `Span`, then a `Sampler` will be used to make the sampling decision: - * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision. - * Else use the global default `Sampler` to determine the sampling decision. -2. If the span is a child of a remote `Span` the sampling decision will be: - * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision. - * Else use the global default `Sampler` to determine the sampling decision. -3. If the span is a child of a local `Span` the sampling decision will be: - * If a "span-scoped" `Sampler` is provided, use it to determine the sampling decision. - * Else keep the sampling decision from the parent. - -### RateLimiting sampler implementation details -The problem we are trying to solve is: -1. Getting QPS based sampling. -2. Providing real sampling probabilities. -3. Minimal overhead. - -Idea is to store the time that we last made a QPS based sampling decision in an atomic. Then we can -use the elapsed time Z since the coin flip to weight our current coin flip. We choose our -probability function P(Z) such that we get the desired sample QPS. We want P(Z) to be very -cheap to compute. - -Let X be the desired QPS. Let Z be the elapsed time since the last sampling decision in seconds. -``` -P(Z) = min(Z * X, 1) -``` - -To see that this is approximately correct, consider the case where we have perfectly distributed -time intervals. Specifically, let X = 1 and Z = 1/N. Then we would have N coin flips per second, -each with probability 1/N, for an expectation of 1 sample per second. - -This will under-sample: consider the case where X = 1 and Z alternates between 0.5 and 1.5. It is -possible to get about 1 QPS by always sampling, but this algorithm only gets 0.75 QPS. diff --git a/work_in_progress/specification/trace/Span.md b/work_in_progress/specification/trace/Span.md deleted file mode 100644 index 9e96b128c4d..00000000000 --- a/work_in_progress/specification/trace/Span.md +++ /dev/null @@ -1,53 +0,0 @@ -# Span - - -... parts of this document moved to [overview.md](../../../specification/overview.md) ... - -A span contains a SpanContext and allows users to record tracing events based on the data model -defined [here][SpanDataModel]. - -## Span structure - - -## Span creation -The implementation MUST allow users to create two types of Spans: -* Root Spans - spans that do not have a parent. -* Child Spans - the parent can be explicitly set or inherit from the Context. - -When creating a Span the implementation MUST allow users to create the Span attached or detached -from the Context, this allows users to manage the interaction with the Context independently of -the Span lifetime: -* Attached to the Context - the newly created Span is attached to the Context. -* Detached from the Context - the newly created Span is not attached to any Context. - -### How Span interacts with Context? -Context interaction represents the process of attaching/detaching a Span to the Context -in order to propagate it in-process (possibly between threads) and between function calls. - -There are two supported implementations for the Context based on how the propagation is implemented: -* With implicit propagation - implicitly passed between function calls and threads, usually -implemented using thread-local variables (e.g. Java [io.grpc.Context][javaContext]) -* With explicit propagation - explicitly passed between function calls and threads (e.g. Go -[context.Context][goContext]) - -When an implicit propagated Context is used, the implementation MUST use scoped objects to -attach/detach a Span (scoped objects represent auto closable objects, e.g. stack allocated -objects in C++): -* When attach/detach an already created Span the API MAY be called `WithSpan`. -* When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`. - -When an explicit propagated Context is used, the implementation MUST create a new Context when a -Span is attached (immutable Context): -* When attach/detach an already created Span the API MAY be called `WithSpan`. -* When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`. - -### Why support Spans that are not attached to the Context? -* Allow users to use the OpenCensus library without using a Context. -* Allow users to have more control for the lifetime of the Span. -* There are cases, for example HTTP/RPC interceptors, where the Span creation and usage happens in -different places, and the user does not have control of the framework to control the Context -propagation. - -[goContext]: https://golang.org/pkg/context -[javaContext]: https://github.com/grpc/grpc-java/blob/master/context/src/main/java/io/grpc/Context.java -[SpanDataModel]: https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/trace/v1/trace.proto diff --git a/work_in_progress/specification/trace/TraceConfig.md b/work_in_progress/specification/trace/TraceConfig.md deleted file mode 100644 index ac7bcd8d868..00000000000 --- a/work_in_progress/specification/trace/TraceConfig.md +++ /dev/null @@ -1,41 +0,0 @@ -# TraceConfig - -Global configuration of the trace service. This allows users to change configs for the default -sampler, maximum events to be kept, etc. - -## TraceParams -Represents the set of parameters that users can control -* Default `Sampler` - used when creating a Span if no specific sampler is given. The default sampler -is a [Probability](Sampling.md) sampler with the probability set to `1/10000`. - -### Limits - -We define limits on the number of attributes, annotations, message events and links on each span -in order to prevent unbounded memory increase for long-running spans. - -When limits are exceeded, implementations should by default preserve the most recently added values -and drop the oldest values. Implementations may make this policy configurable. - -Implementations should track the number of dropped items per span. Some backends provide dedicated -support for tracking these counts. Others do not, but exporters may choose to represent these in -exported spans in some way (for example, as a tag). - -Implementations may support tracking the total number of dropped items in stats as outlined. - -| Item | Default Limit | Measure for dropped items | -| --- | --- | --- | -| Attributes | 32 | opencensus.io/trace/dropped_attributes | -| Annotations | 32 | opencensus.io/trace/dropped_annotations | -| Message Events | 128 | opencensus.io/trace/dropped_message_events | -| Links | 32 | opencensus.io/trace/dropped_links | - -No views should be registered by default on these measures. Users may register views if they -are interested in recording these measures. - -Implementations should provide a way to override the globals per-span. - -## API Summary -* Permanently update the active TraceParams. -* Temporary update the active TraceParams. This API allows changing of the active params for a -certain period of time. No more than one active temporary update can exist at any moment. -* Get current active TraceParams. diff --git a/work_in_progress/typedspans/README.md b/work_in_progress/typedspans/README.md deleted file mode 100644 index 2e0ae06b962..00000000000 --- a/work_in_progress/typedspans/README.md +++ /dev/null @@ -1,154 +0,0 @@ - -# Typed Spans (Draft Proposal) - -In OpenCensus and OpenTracing spans can be created freely and it’s up to the -implementor to annotate them with attributes specific to the represented operation. -This document proposes to add type information to spans and to define and reserve -mandatory and optional attributes depending on the span type. - -## Motivation - -Spans represent specific operations in and between systems. - -Examples for such operations are - -- Local operations like method invocations -- HTTP requests (inbound and outbound) -- Database operations -- Queue/Message publish and consume -- gRPC calls -- Generic RPC operations - -Depending on the type of an operation, additional information is needed to -represent and analyze a span correctly in monitoring systems. - -While both OpenCensus and OpenTracing define conventions that define some reserved -attributes that can be used to add operation-specific information, there is no -mechanism to specify the type of an operation and to ensure that all needed -attributes are set. - -### Proposed types - -Below is a list of types and attributes per type. -This document does not include the final naming of attributes and types. -It is assumed that there will be naming conventions that will be applied eventually. - -There is also no distinction between mandatory and optional attributes as it is assumed -that there will be a dedicated discussion and document for each type linked in this document. - -See [this document by @discostu105](https://docs.google.com/spreadsheets/d/1H0S0BROOgX7zndWF_WL8jb9IW1PN7j3IeryekhX5sKU/edit#gid=0) for type and attribute mappings that exist in OpenCensus and OpenTracing today. - -#### HTTP Client -Represents an outbound HTTP request. - -##### Attributes -These attributes are not covered in the [main spec](../../specification/data-semantic-conventions.md): - -- Route -- User Agent -- Parameters -- Request Headers -- Response Headers - -#### HTTP Server -Represents an inbound HTTP request. - -##### Attributes - -These attributes are not covered in the [main spec](../../specification/data-semantic-conventions.md): - -- User Agent -- Webserver Name -- Remote Address -- Parameters -- Request Headers -- Response Headers - -#### Database Client -Represents a database call. - -##### Attributes - -These attributes are not covered in the [main spec](../../specification/data-semantic-conventions.md): - -- Channel Type (e.g. TCP) - -#### gRPC Client -Represents an outbound gRPC request. - -##### Attributes - -These attributes are not covered in the [main spec](../../specification/data-semantic-conventions.md): - -- Channel Type (e.g. TCP) - -#### gRPC Server -Represents an inbound gRPC request. - -##### Attributes - -These attributes are not covered in the [main spec](../../specification/data-semantic-conventions.md): - -- Channel Type (e.g. TCP) - -#### Remoting Client -Represents an outbound RPC request. - -##### Attributes -- Service Endpoint -- Channel Type (e.g. TCP) -- Channel Endpoint -- Service Name -- Service Method - - -#### Remoting Server -Represents an inbound RPC request. - -##### Attributes -- Service Method -- Service Name -- Service Endpoint -- Protocol Name - - -#### Messaging Consumer -Represents an inbound message. - -##### Attributes -- Vendor Name -- Destination Name -- Destination Type -- Channel Type -- Channel Endpoint -- Operation Type -- Message Id -- Correlation Id - -#### Messaging Producer -Represents an outbound message. - -##### Attributes -- Vendor Name -- Destination Name -- Channel Type -- Channel Endpoint -- Message Id -- Correlation Id - -## Proposal -* Add a field `CanonicalType` that contains the type of span -* Define mandatory and optional attributes per span type -* Provide an API that supports creating typed spans and ensures that at least all - mandatory attributes for this `CanonicalType` are present - -## Challenges and Objections -- Some mandatory attributes for a given type may not be available at the time of creation - -### POC -Here is [a POC for HTTP Client Spans for Node.js and OpenCensus](https://github.com/danielkhan/opencensus-node-typed-span-sample) - -## Action Items -- Define all types -- Agree on type and attribute naming conventions -- Specify each type and agree on mandatory and optional attributes per type