Skip to content

Commit fce1f7c

Browse files
slashmoktoso
slashmo
and
ktoso
authored
Add remaining Otel (0.7.0) semantic attributes (#38)
* Add remaining Otel (0.7.0) semantic attributes * Use SeeAlso instead of See in documentation blocks Co-authored-by: Konrad `ktoso` Malawski <[email protected]>
1 parent cc3033f commit fce1f7c

14 files changed

+967
-158
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -572,7 +572,7 @@ When creating a tracer you need to create two types:
572572
1. Your tracer conforming to `Tracer`
573573
2. A span class conforming to `Span`
574574

575-
> The `Span` conforms to the standard rules defined in [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span), so if unsure about usage patterns, you can refer to this specification and examples referring to it.
575+
> The `Span` conforms to the standard rules defined in [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#span), so if unsure about usage patterns, you can refer to this specification and examples referring to it.
576576
577577
### Defining, injecting and extracting Baggage
578578

‎Sources/Tracing/Span.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import Dispatch
2020
///
2121
/// Creating a `Span` is delegated to a `Tracer` and end users should never create them directly.
2222
///
23-
/// - SeeAlso: For more details refer to the [OpenTelemetry Specification: Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span) which this type is compatible with.
23+
/// - SeeAlso: For more details refer to the [OpenTelemetry Specification: Span](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#span) which this type is compatible with.
2424
public protocol Span: AnyObject {
2525
/// The read-only `Baggage` of this `Span`, set when starting this `Span`.
2626
var baggage: Baggage { get }
@@ -600,7 +600,7 @@ public struct SpanStatus {
600600

601601
/// A code representing the status of a `Span`.
602602
///
603-
/// - SeeAlso: For the semantics of status codes see [OpenTelemetry Specification: setStatus](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-status)
603+
/// - SeeAlso: For the semantics of status codes see [OpenTelemetry Specification: setStatus](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#set-status)
604604
public enum Code {
605605
/// The Span has been validated by an Application developer or Operator to have completed successfully.
606606
case ok

‎Sources/TracingOpenTelemetrySupport/SpanAttribute+DatabaseSemantics.swift

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the Swift Distributed Tracing open source project
4+
//
5+
// Copyright (c) 2021 Apple Inc. and the Swift Distributed Tracing project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
//
10+
// SPDX-License-Identifier: Apache-2.0
11+
//
12+
//===----------------------------------------------------------------------===//
13+
14+
import Tracing
15+
16+
extension SpanAttributeName {
17+
/// - SeeAlso: DatabaseAttributes
18+
public enum Database {
19+
/// - SeeAlso: DatabaseAttributes
20+
public static let system = "db.system"
21+
/// - SeeAlso: DatabaseAttributes
22+
public static let connectionString = "db.connection_string"
23+
/// - SeeAlso: DatabaseAttributes
24+
public static let user = "db.user"
25+
/// - SeeAlso: DatabaseAttributes
26+
public static let name = "db.name"
27+
/// - SeeAlso: DatabaseAttributes
28+
public static let statement = "db.statement"
29+
/// - SeeAlso: DatabaseAttributes
30+
public static let operation = "db.operation"
31+
32+
/// - SeeAlso: DatabaseAttributes.MSSQLAttributes
33+
public enum MSSQL {
34+
/// - SeeAlso: DatabaseAttributes.MSSQLAttributes
35+
public static let instanceName = "db.mssql.instance_name"
36+
}
37+
38+
/// - SeeAlso: DatabaseAttributes.CassandraAttributes
39+
public enum Cassandra {
40+
/// - SeeAlso: DatabaseAttributes.CassandraAttributes
41+
public static let keyspace = "db.cassandra.keyspace"
42+
}
43+
44+
/// - SeeAlso: DatabaseAttributes.HBaseAttributes
45+
public enum HBase {
46+
/// - SeeAlso: DatabaseAttributes.HBaseAttributes
47+
public static let namespace = "db.hbase.namespace"
48+
}
49+
50+
/// - SeeAlso: DatabaseAttributes.RedisAttributes
51+
public enum Redis {
52+
/// - SeeAlso: DatabaseAttributes.RedisAttributes
53+
public static let databaseIndex = "db.redis.database_index"
54+
}
55+
56+
/// - SeeAlso: DatabaseAttributes.MongoDBAttributes
57+
public enum MongoDB {
58+
/// - SeeAlso: DatabaseAttributes.MongoDBAttributes
59+
public static let collection = "db.mongodb.collection"
60+
}
61+
62+
/// - SeeAlso: DatabaseAttributes.SQLAttributes
63+
public enum SQL {
64+
/// - SeeAlso: DatabaseAttributes.SQLAttributes
65+
public static let table = "db.sql.table"
66+
}
67+
}
68+
}
69+
70+
#if swift(>=5.2)
71+
extension SpanAttributes {
72+
/// Semantic database client call attributes.
73+
public var db: DatabaseAttributes {
74+
get {
75+
.init(attributes: self)
76+
}
77+
set {
78+
self = newValue.attributes
79+
}
80+
}
81+
}
82+
83+
/// Semantic conventions for database client calls as defined in the OpenTelemetry spec.
84+
///
85+
/// - SeeAlso: [OpenTelemetry: Database attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/semantic_conventions/database.md)
86+
@dynamicMemberLookup
87+
public struct DatabaseAttributes: SpanAttributeNamespace {
88+
public var attributes: SpanAttributes
89+
90+
public init(attributes: SpanAttributes) {
91+
self.attributes = attributes
92+
}
93+
94+
// MARK: - General
95+
96+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
97+
public init() {}
98+
99+
/// An identifier for the database management system (DBMS) product being used. See [OpenTelemetry: Database attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/semantic_conventions/database.md) for a list of well-known identifiers.
100+
public var system: Key<String> { .init(name: SpanAttributeName.Database.system) }
101+
102+
/// The connection string used to connect to the database. It is recommended to remove embedded credentials.
103+
public var connectionString: Key<String> { .init(name: SpanAttributeName.Database.connectionString) }
104+
105+
/// Username for accessing the database.
106+
public var user: Key<String> { .init(name: SpanAttributeName.Database.user) }
107+
108+
/// If no [tech-specific attribute](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/semantic_conventions/database.md#call-level-attributes-for-specific-technologies)
109+
/// is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails).
110+
///
111+
/// - Note: In some SQL databases, the database name to be used is called "schema name".
112+
public var name: Key<String> { .init(name: SpanAttributeName.Database.name) }
113+
114+
/// The database statement being executed.
115+
///
116+
/// - Note: The value may be sanitized to exclude sensitive information.
117+
public var statement: Key<String> { .init(name: SpanAttributeName.Database.statement) }
118+
119+
/// The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations)
120+
/// such as `findAndModify`, or the SQL keyword.
121+
///
122+
/// - Note: When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this
123+
/// property, but it should be set if the operation name is provided by the library being instrumented.
124+
/// If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
125+
public var operation: Key<String> { .init(name: SpanAttributeName.Database.operation) }
126+
}
127+
128+
// MARK: - MSSQL
129+
130+
/// Semantic MSSQL client call attributes.
131+
public var mssql: MSSQLAttributes {
132+
get {
133+
.init(attributes: self.attributes)
134+
}
135+
set {
136+
self.attributes = newValue.attributes
137+
}
138+
}
139+
140+
/// Semantic conventions for MSSQL client calls as defined in the OpenTelemetry spec.
141+
public struct MSSQLAttributes: SpanAttributeNamespace {
142+
public var attributes: SpanAttributes
143+
144+
public init(attributes: SpanAttributes) {
145+
self.attributes = attributes
146+
}
147+
148+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
149+
public init() {}
150+
151+
/// The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15)
152+
/// connecting to. This name is used to determine the port of a named instance.
153+
///
154+
/// - Note: If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard).
155+
public var instanceName: Key<String> { .init(name: SpanAttributeName.Database.MSSQL.instanceName) }
156+
}
157+
}
158+
159+
// MARK: - Cassandra
160+
161+
/// Semantic Cassandra client call attributes.
162+
public var cassandra: CassandraAttributes {
163+
get {
164+
.init(attributes: self.attributes)
165+
}
166+
set {
167+
self.attributes = newValue.attributes
168+
}
169+
}
170+
171+
/// Semantic conventions for Cassandra client calls as defined in the OpenTelemetry spec.
172+
public struct CassandraAttributes: SpanAttributeNamespace {
173+
public var attributes: SpanAttributes
174+
175+
public init(attributes: SpanAttributes) {
176+
self.attributes = attributes
177+
}
178+
179+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
180+
public init() {}
181+
182+
/// The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute.
183+
public var keyspace: Key<String> { .init(name: SpanAttributeName.Database.Cassandra.keyspace) }
184+
}
185+
}
186+
187+
// MARK: - HBase
188+
189+
/// Semantic HBase client call attributes.
190+
public var hbase: HBaseAttributes {
191+
get {
192+
.init(attributes: self.attributes)
193+
}
194+
set {
195+
self.attributes = newValue.attributes
196+
}
197+
}
198+
199+
/// Semantic conventions for HBase client calls as defined in the OpenTelemetry spec.
200+
public struct HBaseAttributes: SpanAttributeNamespace {
201+
public var attributes: SpanAttributes
202+
203+
public init(attributes: SpanAttributes) {
204+
self.attributes = attributes
205+
}
206+
207+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
208+
public init() {}
209+
210+
/// The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed.
211+
/// To be used instead of the generic `db.name` attribute.
212+
public var namespace: Key<String> { .init(name: SpanAttributeName.Database.HBase.namespace) }
213+
}
214+
}
215+
216+
// MARK: - Redis
217+
218+
/// Semantic Redis client call attributes.
219+
public var redis: RedisAttributes {
220+
get {
221+
.init(attributes: self.attributes)
222+
}
223+
set {
224+
self.attributes = newValue.attributes
225+
}
226+
}
227+
228+
/// Semantic conventions for Redis client calls as defined in the OpenTelemetry spec.
229+
public struct RedisAttributes: SpanAttributeNamespace {
230+
public var attributes: SpanAttributes
231+
232+
public init(attributes: SpanAttributes) {
233+
self.attributes = attributes
234+
}
235+
236+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
237+
public init() {}
238+
239+
/// The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select),
240+
/// provided as an integer. To be used instead of the generic `db.name` attribute.
241+
public var databaseIndex: Key<Int> { .init(name: SpanAttributeName.Database.Redis.databaseIndex) }
242+
}
243+
}
244+
245+
// MARK: - MongoDB
246+
247+
/// Semantic MongoDB client call attributes.
248+
public var mongodb: MongoDBAttributes {
249+
get {
250+
.init(attributes: self.attributes)
251+
}
252+
set {
253+
self.attributes = newValue.attributes
254+
}
255+
}
256+
257+
/// Semantic conventions for MongoDB client calls as defined in the OpenTelemetry spec.
258+
public struct MongoDBAttributes: SpanAttributeNamespace {
259+
public var attributes: SpanAttributes
260+
261+
public init(attributes: SpanAttributes) {
262+
self.attributes = attributes
263+
}
264+
265+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
266+
public init() {}
267+
268+
/// The collection being accessed within the database stated in `db.name`.
269+
public var collection: Key<String> { .init(name: SpanAttributeName.Database.MongoDB.collection) }
270+
}
271+
}
272+
273+
// MARK: - SQL
274+
275+
/// Semantic SQL client call attributes.
276+
public var sql: SQLAttributes {
277+
get {
278+
.init(attributes: self.attributes)
279+
}
280+
set {
281+
self.attributes = newValue.attributes
282+
}
283+
}
284+
285+
/// Semantic conventions for SQL client calls as defined in the OpenTelemetry spec.
286+
public struct SQLAttributes: SpanAttributeNamespace {
287+
public var attributes: SpanAttributes
288+
289+
public init(attributes: SpanAttributes) {
290+
self.attributes = attributes
291+
}
292+
293+
public struct NestedSpanAttributes: NestedSpanAttributesProtocol {
294+
public init() {}
295+
296+
/// The name of the primary table that the operation is acting upon, including the schema name (if applicable).
297+
///
298+
/// - Note: It is not recommended to attempt any client-side parsing of `db.statement` just to get this property,
299+
/// but it should be set if it is provided by the library being instrumented.
300+
/// If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
301+
public var table: Key<String> { .init(name: SpanAttributeName.Database.SQL.table) }
302+
}
303+
}
304+
}
305+
#endif

‎Sources/TracingOpenTelemetrySupport/SpanAttribute+EndUser.swift renamed to ‎Sources/TracingOpenTelemetrySupport/SpanAttribute+EndUserSemantics.swift

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@
1414
import Tracing
1515

1616
extension SpanAttributeName {
17-
/// - See: EndUserAttributes
17+
/// - SeeAlso: EndUserAttributes
1818
public enum EndUser {
19-
/// - See: EndUserAttributes
19+
/// - SeeAlso: EndUserAttributes
2020
public static let id = "enduser.id"
21-
/// - See: EndUserAttributes
21+
/// - SeeAlso: EndUserAttributes
2222
public static let role = "enduser.role"
23-
/// - See: EndUserAttributes
23+
/// - SeeAlso: EndUserAttributes
2424
public static let scope = "enduser.scope"
2525
}
2626
}
@@ -40,7 +40,7 @@ extension SpanAttributes {
4040

4141
/// End-user-related semantic conventions as defined in the OpenTelemetry spec.
4242
///
43-
/// - SeeAlso: [OpenTelemetry: General identity attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/b70565d5a8a13d26c91fb692879dc874d22c3ac8/specification/trace/semantic_conventions/span-general.md#general-identity-attributes) (as of August 2020)
43+
/// - SeeAlso: [OpenTelemetry: General identity attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/semantic_conventions/span-general.md#general-identity-attributes)
4444
@dynamicMemberLookup
4545
public struct EndUserAttributes: SpanAttributeNamespace {
4646
public var attributes: SpanAttributes

0 commit comments

Comments
 (0)