Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add middleware to process semantic conventions #1194

Closed
wants to merge 4 commits into from
Closed

Add middleware to process semantic conventions #1194

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
da4425d
Add middleware to process semantic conventions
ivomagi Nov 4, 2020
c5ef9a6
Process middleware description change.
ivomagi Nov 4, 2020
c011cd5
Changed example used to describe the middleware
ivomagi Nov 4, 2020
99a1ed7
Update process.md
ivomagi Nov 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions specification/resource/semantic_conventions/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,59 @@ Examples for some Ruby runtimes
| --- | --- | --- | --- |
| MRI | ruby | 2.7.1 | ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-darwin19] |
| TruffleRuby | truffleruby | 2.6.2 | truffleruby (Shopify) 20.0.0-dev-92ed3059, like ruby 2.6.2, GraalVM CE Native [x86_64-darwin] |

## Process middlewares

**type:** `process.middleware`

**Description:** The single middleware instance which is monitored on this process.

| Attribute | Description | Example | Required |
|---|---|---|--|
| process.middleware.type | Standardized attribute, specifying the type of middleware on the runtime. This attribute adds value to traces, giving the opportunity to visualise different kind of middleware using different representation in server-side. The supported values of type are `as` (application server), `ws` (web server), `dbs` (database server) or `mom` (message-oriented middleware). | `as` | No |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is a database server middleware?

The means of communicating with a database server, such as JDBC, is middleware, but I'm not sure that the database server itself is.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being new to Otel I might be on a wrong track here as the databases seem to be treated as downstream dependencies vs part of the trace itself. But there is no reason why there could not be agents monitoring the databases themselves and building spans out of the database as well. And for example with Druid and other JVM-based databases, it is rather straightforward as of now. Also the middleware definition lists databases as one of the members of middleware family.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which "middleware definition" are you referring to?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I was too optimistic when refering to it as "definition", as for example Wikipedia version of it does not count the database as middleware and maybe rightfully so. This however does not change the fact that many of the databases (Druid, Cassandra, Derby) do run on a Java runtime and could very well be part of the trace itself (vs downstream dependencies). That being said, maybe Otel does treat databases as not part of the trace at all or treats them special members within the trace?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think midleware is not really what you mean anyway. It is used by many webframeworks to mean something different, e.g. https://docs.djangoproject.com/en/3.1/topics/http/middleware/ or https://aspnetmonsters.com/2016/03/2016-02-28-what-is-middleware-anyway/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are numerous traces in the wild internet, trying to define middleware. And maybe I am off the best path here with the naming, but it does not seem to change the need to enhance the spans in the trace with the information about what kind of "middleware" they are running. This is also something that most existing (non-otel-compliant) vendors offer and having this clearly defined in Otel should greatly reduce the friction in migrating from an existing APM vendor to standards-based solutions.

| process.middleware.name | The name of the middleware running on this process. | `WildFly` | No |
| process.middleware.version | The version of the middleware of this process, as returned by the middleware (preferably during runtime) without modification. | `21.0.0` | No |
| process.middleware.description | An additional description about the middleware of the process. | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | No |

`process.middleware.type` MUST be set to one of the values from `as` (application server), `ws` (web server), `dbs` (database server) or `mom` (message-oriented middleware).
`process.middleware.name` SHOULD be set to the values listed in examples below. If none of the listed values apply, a custom value best describing the runtime MAY be used.

***Application server middlewares:***

Information describing the application server should be captured using the values acquired from the middleware specific API, preferably during runtime. As an example - for Java application servers supporting Servlet API this information can be captured by invoking `ServletContext.getServerInfo()` during runtime and parsing the result.

Examples for some application server middlewares:

| Name | `process.middleware.name` | `process.middleware.version` | `process.middleware.description` |
| --- | --- | --- | --- |
| Apache Tomcat | `Tomcat` | `9.0.39` | `Apache Tomcat/9.0.39` |
| Eclipse Jetty | `Jetty` | `9.4.33` | `jetty/9.4.33.v20201020` |
| Eclipse GlassFish | `GlassFish` | `5.0` | `GlassFish Server Open Source Edition 5.0` |
| WildFly | `WildFly` | `21.0.0` | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` |

***Web server middlewares:***

Examples for some web server middlewares:

| Name | `process.middleware.name` | `process.middleware.version` | `process.middleware.description` |
| --- | --- | --- | --- |
| nginx | `nginx` | `1.19.3` | `nginx version: nginx/1.19.3` |
| Apache HTTP Server | `apache` | `2.4.41` | `Apache/2.4.41 (Ubuntu) OpenSSL/1.1.1f` |

***Message-oriented middlewares:***

Examples for some message-oriented middlewares:

| Name | `process.middleware.name` | `process.middleware.version` | `process.middleware.description` |
| --- | --- | --- | --- |
| Apache Kafka | `Kafka` | `2.6.0` | `2.6.0 (Commit:62abe01bee039651)` |

***Database middlewares:***

Examples for some database middlewares:

| Name | `process.middleware.name` | `process.middleware.version` | `process.middleware.description` |
| --- | --- | --- | --- |
| Apache Druid | `Druid` | `0.15.0` | `0.15.0-incubating` |
| MySQL | `MySQL` | `5.7.28` | `5.7.28-0ubuntu0.19.04.2` |