diff --git a/examples/debugging/README.md b/examples/debugging/README.md new file mode 100644 index 00000000..eadd55be --- /dev/null +++ b/examples/debugging/README.md @@ -0,0 +1,27 @@ +# Debugging + +Currently, grpc provides two major tools to help user debug issues, which are logging and channelz. + +## Logs + +gRPC has put substantial logging instruments on critical paths of gRPC to help users debug issues. The [Environment Variables](https://github.com/grpc/grpc-node/blob/master/doc/environment_variables.md) doc describes the environment variables that control debug logging. + +To enable full debug logging, run the code with the following environment variables: `GRPC_TRACE=all GRPC_VERBOSITY=DEBUG`. + +## Channelz + +We also provide a runtime debugging tool, Channelz, to help users with live debugging. + +See the channelz blog post here ([link](https://grpc.io/blog/a-short-introduction-to-channelz/)) for details about how to use channelz service to debug live program. + +## Try it + +The example is able to showcase how logging and channelz can help with debugging. See the channelz blog post linked above for full explanation. + +``` +node server.js +``` + +``` +node client.js +``` diff --git a/examples/debugging/client.js b/examples/debugging/client.js new file mode 100644 index 00000000..9ae62bdc --- /dev/null +++ b/examples/debugging/client.js @@ -0,0 +1,97 @@ +/* + * + * Copyright 2025 gRPC authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +const grpc = require('@grpc/grpc-js'); +const protoLoader = require('@grpc/proto-loader'); +const parseArgs = require('minimist'); + +var PROTO_PATH = __dirname + '/../protos/helloworld.proto'; + +const packageDefinition = protoLoader.loadSync( + PROTO_PATH, + {keepCase: true, + longs: String, + enums: String, + defaults: true, + oneofs: true + }); +var helloProto = grpc.loadPackageDefinition(packageDefinition).helloworld; + +function serverBindPort(server, port) { + return new Promise((resolve, reject) => { + server.bindAsync(port, grpc.ServerCredentials.createInsecure(), (error, port) => { + if (error) { + reject(error); + } else { + resolve(port); + } + }) + }); +} + +const addressString = 'ipv4:///127.0.0.1:10001,127.0.0.1:10002,127.0.0.1:10003'; + +function callSayHello(client, name) { + return new Promise((resolve, reject) => { + const deadline = new Date(); + deadline.setMilliseconds(deadline.getMilliseconds() + 150); + client.sayHello({name}, {deadline}, (error, response) => { + if (error) { + reject(error); + } else { + resolve(response); + } + }); + }); +} + +async function main() { + const argv = parseArgs(process.argv.slice(2), { + string: ['addr', 'name'], + default: {addr: 'localhost:50051', name: 'world'} + }); + + // Set up the server serving channelz service. + const channelzServer = new grpc.Server(); + grpc.addAdminServicesToServer(channelzServer); + await serverBindPort(channelzServer, argv.addr); + + const roundRobinServiceConfig = { + methodConfig: [], + loadBalancingConfig: [{ round_robin: {} }] + }; + const client = new helloProto.Greeter(addressString, grpc.credentials.createInsecure(), {'grpc.service_config': JSON.stringify(roundRobinServiceConfig)}); + + // Contact the server and print out its response + + // Make 100 SayHello RPCs + for (let i = 0; i < 100; i++) { + try { + const response = await callSayHello(client, argv.name); + console.log(`Greeting: ${response.message}`); + } catch (e) { + console.log(`could not greet: ${e.message}`); + } + } + + // Unless you exit the program (e.g. CTRL+C), channelz data will be available for querying. + // Users can take time to examine and learn about the info provided by channelz. + setInterval(() => {}, 10000); +} + +main(); diff --git a/examples/debugging/server.js b/examples/debugging/server.js new file mode 100644 index 00000000..c3685fa5 --- /dev/null +++ b/examples/debugging/server.js @@ -0,0 +1,79 @@ +/* + * + * Copyright 2025 gRPC authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +const grpc = require('@grpc/grpc-js'); +const protoLoader = require('@grpc/proto-loader'); + +var PROTO_PATH = __dirname + '/../protos/helloworld.proto'; + +const packageDefinition = protoLoader.loadSync( + PROTO_PATH, + {keepCase: true, + longs: String, + enums: String, + defaults: true, + oneofs: true + }); +var helloProto = grpc.loadPackageDefinition(packageDefinition).helloworld; + +const greeterImplementation = { + sayHello: (call, callback) => { + callback(null, { message: `Hello ${call.request.name}`}); + } +}; + +const slowGreeterImplementation = { + sayHello: (call, callback) => { + const waitTimeMs = 100 + (Math.random() * 100)|0; + setTimeout(() => { + callback(null, { message: `Hello ${call.request.name}`}); + }, waitTimeMs); + } +} + +function serverBindPort(server, port) { + return new Promise((resolve, reject) => { + server.bindAsync(`0.0.0.0:${port}`, grpc.ServerCredentials.createInsecure(), (error, port) => { + if (error) { + reject(error); + } else { + resolve(port); + } + }) + }); +} + +async function main() { + const channelzServer = new grpc.Server(); + grpc.addAdminServicesToServer(channelzServer); + await serverBindPort(channelzServer, 50052); + + const server1 = new grpc.Server(); + server1.addService(helloProto.Greeter.service, greeterImplementation); + await serverBindPort(server1, 10001); + + const server2 = new grpc.Server(); + server2.addService(helloProto.Greeter.service, greeterImplementation); + await serverBindPort(server2, 10002); + + const server3 = new grpc.Server(); + server3.addService(helloProto.Greeter.service, slowGreeterImplementation); + await serverBindPort(server3, 10003); +} + +main();