Skip to content

Commit

Permalink
Document ObservabilityOptions plus prefix _observabilityOptions
Browse files Browse the repository at this point in the history
  • Loading branch information
@odeke-em
odeke-em committed Sep 30, 2024
1 parent d0a338d commit bf187e3
Show file tree
Hide file tree
Showing 12 changed files with 56 additions and 49 deletions.
2 changes: 1 addition & 1 deletion observability-test/batch-transaction.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ describe('BatchTransaction', () => {
batchTransaction = new BatchTransaction(SESSION as {} as Session);
batchTransaction.session = SESSION as {} as Session;
batchTransaction.id = ID;
batchTransaction.observabilityOptions_ = {tracerProvider: provider};
batchTransaction._observabilityOptions = {tracerProvider: provider};
REQUEST.callsFake((_, callback) => callback(null, RESPONSE));
});

Expand Down
2 changes: 1 addition & 1 deletion observability-test/database.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ describe('Database', () => {
database = new Database(INSTANCE, NAME, POOL_OPTIONS);
database.parent = INSTANCE;
database.databaseRole = 'parent_role';
database.observabilityOptions_ = {
database._observabilityOptions = {
tracerProvider: provider,
enableExtendedTracing: false,
};
Expand Down
32 changes: 15 additions & 17 deletions observability-test/spanner.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,16 @@ describe('EndToEnd', () => {
});

beforeEach(async () => {
const setupResult = await setup();
traceExporter = new InMemorySpanExporter();
const sampler = new AlwaysOnSampler();
const provider = new NodeTracerProvider({
sampler: sampler,
exporter: traceExporter,
});
const setupResult = await setup({
tracerProvider: provider,
enableExtendedTracing: false,
});
spanner = setupResult.spanner;
server = setupResult.server;
spannerMock = setupResult.spannerMock;
Expand All @@ -143,21 +152,10 @@ describe('EndToEnd', () => {
mock.StatementResult.updateCount(1)
);

traceExporter = new InMemorySpanExporter();
const sampler = new AlwaysOnSampler();

const provider = new NodeTracerProvider({
sampler: sampler,
exporter: traceExporter,
});
provider.addSpanProcessor(new SimpleSpanProcessor(traceExporter));

const instance = spanner.instance('instance');
database = instance.database('database');
database.observabilityOptions_ = {
tracerProvider: provider,
enableExtendedTracing: false,
};
});

afterEach(() => {
Expand Down Expand Up @@ -488,26 +486,26 @@ describe('ObservabilityOptions injection and propagation', async () => {

it('Passed into Spanner, Instance and Database', done => {
// Ensure that the same observability configuration is set on the Spanner client.
assert.deepStrictEqual(spanner.observabilityOptions_, observabilityOptions);
assert.deepStrictEqual(spanner._observabilityOptions, observabilityOptions);

// Acquire a handle to the Instance through spanner.instance.
const instanceByHandle = spanner.instance('instance');
assert.deepStrictEqual(
instanceByHandle.observabilityOptions_,
instanceByHandle._observabilityOptions,
observabilityOptions
);

// Create the Instance by means of a constructor directly.
const instanceByConstructor = new Instance(spanner, 'myInstance');
assert.deepStrictEqual(
instanceByConstructor.observabilityOptions_,
instanceByConstructor._observabilityOptions,
observabilityOptions
);

// Acquire a handle to the Database through instance.database.
const databaseByHandle = instanceByHandle.database('database');
assert.deepStrictEqual(
databaseByHandle.observabilityOptions_,
databaseByHandle._observabilityOptions,
observabilityOptions
);

Expand All @@ -517,7 +515,7 @@ describe('ObservabilityOptions injection and propagation', async () => {
'myDatabase'
);
assert.deepStrictEqual(
databaseByConstructor.observabilityOptions_,
databaseByConstructor._observabilityOptions,
observabilityOptions
);

Expand Down
2 changes: 1 addition & 1 deletion observability-test/table.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ describe('Table', () => {
extend(Table, TableCached);
table = new Table(DATABASE, NAME);
transaction = new FakeTransaction();
table.observabilityOptions_ = {tracerProvider: provider};
table._observabilityOptions = {tracerProvider: provider};
});

afterEach(() => {
Expand Down
6 changes: 3 additions & 3 deletions src/batch-transaction.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ class BatchTransaction extends Snapshot {

const traceConfig: traceConfig = {
sql: query,
opts: this.observabilityOptions_,
opts: this._observabilityOptions,
};
return startTrace(
'BatchTransaction.createQueryPartitions',
Expand Down Expand Up @@ -182,7 +182,7 @@ class BatchTransaction extends Snapshot {
*/
createPartitions_(config, callback) {
const traceConfig: traceConfig = {
opts: this.observabilityOptions_,
opts: this._observabilityOptions,
};

return startTrace(
Expand Down Expand Up @@ -259,7 +259,7 @@ class BatchTransaction extends Snapshot {
*/
createReadPartitions(options, callback) {
const traceConfig: traceConfig = {
opts: this.observabilityOptions_,
opts: this._observabilityOptions,
};

return startTrace(
Expand Down
28 changes: 14 additions & 14 deletions src/database.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@ class Database extends common.GrpcServiceObject {
databaseDialect?: EnumKey<
typeof databaseAdmin.spanner.admin.database.v1.DatabaseDialect
> | null;
observabilityOptions_?: ObservabilityOptions;
_observabilityOptions?: ObservabilityOptions;
constructor(
instance: Instance,
name: string,
Expand Down Expand Up @@ -467,7 +467,7 @@ class Database extends common.GrpcServiceObject {
Object.assign({}, queryOptions),
Database.getEnvironmentQueryOptions()
);
this.observabilityOptions_ = instance.observabilityOptions_;
this._observabilityOptions = instance._observabilityOptions;
}
/**
* @typedef {array} SetDatabaseMetadataResponse
Expand Down Expand Up @@ -693,7 +693,7 @@ class Database extends common.GrpcServiceObject {

const sessions = (resp!.session || []).map(metadata => {
const session = this.session(metadata.name!);
session.observabilityOptions_ = this.observabilityOptions_;
session._observabilityOptions = this._observabilityOptions;
session.metadata = metadata;
return session;
});
Expand Down Expand Up @@ -738,7 +738,7 @@ class Database extends common.GrpcServiceObject {
const id = identifier.transaction;
const transaction = new BatchTransaction(session, options);
transaction.id = id;
transaction.observabilityOptions_ = this.observabilityOptions_;
transaction._observabilityOptions = this._observabilityOptions;
transaction.readTimestamp = identifier.timestamp as PreciseDate;
return transaction;
}
Expand Down Expand Up @@ -828,7 +828,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrCallback as TimestampBounds)
: {};

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
return startTrace('Database.createBatchTransaction', q, span => {
this.pool_.getSession((err, session) => {
if (err) {
Expand Down Expand Up @@ -1086,7 +1086,7 @@ class Database extends common.GrpcServiceObject {
/CREATE TABLE `*([^\s`(]+)/
)![1];
const table = this.table(tableName!);
table.observabilityOptions_ = this.observabilityOptions_;
table._observabilityOptions = this._observabilityOptions;
callback!(null, table, operation!, resp!);
});
}
Expand Down Expand Up @@ -1875,7 +1875,7 @@ class Database extends common.GrpcServiceObject {
delete (gaxOpts as GetSessionsOptions).pageToken;
}

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
return startTrace('Database.getSessions', q, span => {
this.request<
google.spanner.v1.ISession,
Expand All @@ -1897,7 +1897,7 @@ class Database extends common.GrpcServiceObject {
sessionInstances = sessions.map(metadata => {
const session = self.session(metadata.name!);
session.metadata = metadata;
session.observabilityOptions_ = this.observabilityOptions_;
session._observabilityOptions = this._observabilityOptions;
return session;
});
}
Expand Down Expand Up @@ -2058,7 +2058,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrCallback as TimestampBounds)
: {};

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
return startTrace('Database.getSnapshot', q, span => {
this.pool_.getSession((err, session) => {
if (err) {
Expand Down Expand Up @@ -2159,7 +2159,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrCallback as GetTransactionOptions)
: {};

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
return startTrace('Database.getTransaction', q, span => {
this.pool_.getSession((err, session, transaction) => {
if (options.requestOptions) {
Expand Down Expand Up @@ -2786,7 +2786,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrCallback as TimestampBounds)
: {};

const q = {sql: query, opts: this.observabilityOptions_};
const q = {sql: query, opts: this._observabilityOptions};
return startTrace('Database.run', q, span => {
this.runStream(query, options)
.on('error', err => {
Expand Down Expand Up @@ -3007,7 +3007,7 @@ class Database extends common.GrpcServiceObject {
options?: TimestampBounds
): PartialResultStream {
const proxyStream: Transform = through.obj();
const q = {sql: query, opts: this.observabilityOptions_};
const q = {sql: query, opts: this._observabilityOptions};
return startTrace('Database.runStream', q, span => {
this.pool_.getSession((err, session) => {
if (err) {
Expand Down Expand Up @@ -3185,7 +3185,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrRunFn as RunTransactionOptions)
: {};

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
startTrace('Database.runTransaction', q, span => {
this.pool_.getSession((err, session?, transaction?) => {
if (err) {
Expand Down Expand Up @@ -3578,7 +3578,7 @@ class Database extends common.GrpcServiceObject {
? (optionsOrCallback as CallOptions)
: {};

const q = {opts: this.observabilityOptions_};
const q = {opts: this._observabilityOptions};
return startTrace('Database.writeAtLeastOnce', q, span => {
this.pool_.getSession((err, session?, transaction?) => {
if (err && isSessionNotFoundError(err as grpc.ServiceError)) {
Expand Down
6 changes: 3 additions & 3 deletions src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ class Spanner extends GrpcService {
resourceHeader_: {[k: string]: string};
routeToLeaderEnabled = true;
directedReadOptions: google.spanner.v1.IDirectedReadOptions | null;
observabilityOptions_: ObservabilityOptions | undefined;
_observabilityOptions: ObservabilityOptions | undefined;

/**
* Placeholder used to auto populate a column with the commit timestamp.
Expand Down Expand Up @@ -368,7 +368,7 @@ class Spanner extends GrpcService {
[CLOUD_RESOURCE_HEADER]: this.projectFormattedName_,
};
this.directedReadOptions = directedReadOptions;
this.observabilityOptions_ = options.observabilityOptions;
this._observabilityOptions = options.observabilityOptions;
}

/**
Expand Down Expand Up @@ -589,7 +589,7 @@ class Spanner extends GrpcService {
return;
}
const instance = this.instance(formattedName);
instance.observabilityOptions_ = this.observabilityOptions_;
instance._observabilityOptions = this._observabilityOptions;
callback!(null, instance, operation, resp);
}
);
Expand Down
8 changes: 4 additions & 4 deletions src/instance.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ class Instance extends common.GrpcServiceObject {
databases_: Map<string, Database>;
metadata?: IInstance;
resourceHeader_: {[k: string]: string};
observabilityOptions_?: ObservabilityOptions;
_observabilityOptions?: ObservabilityOptions;
constructor(spanner: Spanner, name: string) {
const formattedName_ = Instance.formatName_(spanner.projectId, name);
const methods = {
Expand Down Expand Up @@ -241,7 +241,7 @@ class Instance extends common.GrpcServiceObject {
this.resourceHeader_ = {
[CLOUD_RESOURCE_HEADER]: this.formattedName_,
};
this.observabilityOptions_ = spanner.observabilityOptions_;
this._observabilityOptions = spanner._observabilityOptions;
}

/**
Expand Down Expand Up @@ -928,7 +928,7 @@ class Instance extends common.GrpcServiceObject {
return;
}
const database = this.database(name, poolOptions || poolCtor);
database.observabilityOptions_ = this.observabilityOptions_;
database._observabilityOptions = this._observabilityOptions;
callback(null, database, operation, resp);
}
);
Expand Down Expand Up @@ -978,7 +978,7 @@ class Instance extends common.GrpcServiceObject {
const key = name.split('/').pop() + optionsKey;
if (!this.databases_.has(key!)) {
const db = new Database(this, name, poolOptions, queryOptions);
db.observabilityOptions_ = this.observabilityOptions_;
db._observabilityOptions = this._observabilityOptions;
this.databases_.set(key!, db);
}
return this.databases_.get(key!)!;
Expand Down
9 changes: 9 additions & 0 deletions src/instrument.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,15 @@ interface SQLStatement {
sql: string;
}

/*
* ObservabilityOptions defines the configuration with which
* startTrace may be invoked if set.
* @param [tracerProvider] is the injected TracerProvider to use,
* otherwise the global TracerProvider shall be used.
* @param [enableExtendedTracing] when set signifies that spans started
* with an accompanying an SQL statement shall be annotated with that SQL.
* Alternatively, you could set environment variable `SPANNER_ENABLE_EXTENDED_TRACING=true`.
*/
interface ObservabilityOptions {
tracerProvider: TracerProvider;
enableExtendedTracing?: boolean;
Expand Down
6 changes: 3 additions & 3 deletions src/table.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ const POSTGRESQL = 'POSTGRESQL';
class Table {
database: Database;
name: string;
observabilityOptions_?: ObservabilityOptions;
_observabilityOptions?: ObservabilityOptions;
constructor(database: Database, name: string) {
/**
* The {@link Database} instance of this {@link Table} instance.
Expand All @@ -113,7 +113,7 @@ class Table {
* @type {string}
*/
this.name = name;
this.observabilityOptions_ = database.observabilityOptions_;
this._observabilityOptions = database._observabilityOptions;
}
/**
* Create a table.
Expand Down Expand Up @@ -1081,7 +1081,7 @@ class Table {
callback: CommitCallback
): void {
const traceConfig: traceConfig = {
opts: this.observabilityOptions_,
opts: this._observabilityOptions,
};

startTrace('Table.' + method, traceConfig, span => {
Expand Down
2 changes: 1 addition & 1 deletion src/transaction.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,7 @@ export class Snapshot extends EventEmitter {
queryOptions?: IQueryOptions;
resourceHeader_: {[k: string]: string};
requestOptions?: Pick<IRequestOptions, 'transactionTag'>;
observabilityOptions_?: ObservabilityOptions;
_observabilityOptions?: ObservabilityOptions;

/**
* The transaction ID.
Expand Down
2 changes: 1 addition & 1 deletion test/spanner.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5015,7 +5015,7 @@ describe('Spanner with mock server', () => {
const opts: typeof ObservabilityOptions = {tracerProvider: provider};
startTrace('aSpan', {opts: opts}, span => {
const database = newTestDatabase();
database.observabilityOptions_ = opts;
database._observabilityOptions = opts;

async function runIt() {
const query = {
Expand Down

0 comments on commit bf187e3

Please sign in to comment.