Merge pull request #2969 from murgatroid99/debugging_example

Add debugging example

Author: murgatroid99

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
+```

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();

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();