A Condensed Treatment From The Complete Bestiary For Systems Administrators
To set the scene: you have fought tooth and claw for your first developer job. Months, if not years in training have lead you to this moment. You are with your team, and you are navigating a winding path of steep cliffs of technical debt, dense undergrowth of product requirements, and tall canopies of deployment. You can hear user stories chittering and cackling unseen in the wilds.
Something is wrong, though. One or more of the services your team’s product relies on cannot connect, so your team’s workflow for testing and deployment is now stopped. “It’s a network issue,” one of the senior developers says, pointing at a flamboyantly large vermillion bird perched on one of the network cables. “They squeeze the cables so the bits can’t get through.” You squint at it. Wasn’t there a similar bird for that one user story that raving network guy put in about network saturation? But the senior developer has more experience, so they probably know what they’re talking about.
You hesitate to get closer. The bird does have a mean look in its eye, reminding you of dinosaurs gone by and that it wasn’t that long ago that mammals were just little rodents.
The senior developer pulls out their phone, snaps a picture, and emails it to the network team with no subject. The other developers start making camp – someone gets out a coffee grinder, a fire is quickly made, and before long mugs are being filled and thumbs are being twiddled. You, however, are incensed. All this effort to get here, and we’re just going to wait? You have to prove your worth! There are user stories right there just over the hill that need to be worked on!
Now, a network admin is going to manage their own task queue. But when choosing network issues to deal with, the sighting with the most detail is going to get a helpful response fastest. Let’s take a look at the report you can make as a junior developer that will get that bird moved.
Anatomy of a Ticket
Subject:
Front end service hosted on [address] cannot connect to back end service hosted on [address]
Body:
Hi, I'm a junior developer on [team] and our front end service stopped being able to connect to back end service. We noticed this at [time] and the last time we see it able to connect was [earlier time]. The impact of this is [impact].
Additional information: DATEattachment.txt
[commands run to connect to service][ping information]
This is a ticket that is going to get prioritized over a no-subject screenshot. The no-subject screenshot is going to be replied to with a series of basic troubleshooting questions, eventually. There is enough information here that your network administrator may even be able to solve the problem without further involvement from your team, and will simply reply with “fixed. pls try now” in a ticket closure response.
Here’s why:
Subject
In the ticket queue that administrators work from, their work is organized by priority, time received, and subject line. (no subject) means that some tier 1 technician or dispatcher has to open the ticket, decide what the issue is, and put a value for the subject line. A screenshot of a service failing to connect means that the tier 1 technician has to correctly guess what the issue is from the screenshot. As a junior developer, do you know everything about what other teams are doing? That tier 1 is just barely learning how to approach a router without spooking it. Help them out by giving them a subject line that will enable them to immediately kick this ticket up the chain.
Body
Your problem statement is in the first sentence. You establish your relationship to the issue as a point of contact, and the number of syllables that should be used when speaking to you. (No one wants more syllables.) You mention when the problem first started occurring, which means that the network admin or network technician will know when in the logs to start looking for the issue, or they can correlate this report with other sightings they’re receiving.
Additional Information
[commands run to connect to service] The network guy may have heard some developer words before, and the systems administrator may have grudgingly learned some basic scripting skills because operations has become DevOps. But showing them how to re-create the problem you’re experiencing means they don’t have to look up what you’re doing or learn about the services you’re using just to start solving the problem, they can just copy the command you’re running and look to see if they get the same error message.
[ping information] This last piece of additional information is going to put a gold star next to your name on any subsequent sighting report of any unusual beasts you submit to your organization’s IT team. Because very often, they will know the exact location of this bird from this information alone. You need to collect five to six pieces of information for this portion of the ticket. I know that sounds like a lot, but I promise that it can be done in under a minute.
- The local IP address or hostname of the frontend service’s host server.
Windows:
ipconfig | findstr IPv4
IPv4 Address. . . . . . . . . . . : 192.168.1.10
*nix:
hostname -I
ip addr
- The same for the service you’re trying to connect to. Same commands as above (if you can’t connect, try to know what the hostname is for the future when you can connect.)
- Pinging a neighbor of the server your service is on. This is semi optional, and whether it would work in the first place depends on whether you allow your servers to interact with each other in the playpen. Get an IP address using a command above, and try this command from the server you want to connect to the back end:
ping [address] - Pinging the router your server expects to use to talk to the other networks. Learn who this router is by one of the following commands:
Windows:
ipconfig | findstr Gateway
Default Gateway . . . . . . . . . : 192.168.1.1
*nix:
ip route show | grep default
and then ping [address]
ping 8.8.8.8ping www.google.com
Dump the output of all of these into a text file and attach it to your sighting report. The first ping can reveal a problem with a cryptic creature known as the network switch, they are simple, shy beasts but easily become enraged if loop conditions are created which force herds of packets into whirling vortexes. The second ping will reveal if your switch is properly connected to a router. The third will reveal if that router is cranky. The fourth… whether or not DNS is working. With these four pieces of information, your network administrator will barely need to talk to you at all, and that will make you very interesting.
You sip your coffee. A light whirring sounds from overhead, and a drone with a peanut butter seed ball suspended from it travels along above the wires, coming vaguely from the direction of the dungeon where you know the organization pens up the network admins. The drone hovers over the bird for a moment, then continues on. The bird takes off and follows it.
Your phone pips with a notification. “fixed. pls try now”
For more funny and fantastical stories about technology, please see the “Mythical Beasts” series here on my website. Thank you for reading. Let me know if you have any mythical beasts you’d like me to write about in the comments!