docs: def heartbeat(self, status_info):
          '''
          Update service status, indicating "up"-ness.
  
          Args:
              status_info (dict): a dictionary representing the status of the
              service
  
          `status_info` must have at least the fields 'role', 'load', and
          'ttl'. Some additional fields are populated automatically by this
          method. If the field 'id' is absent, it will be generated by rethinkdb.
  
          See the ServiceRegistry class-level documentation for more information
          about the various fields.
  
          Returns:
              On success, returns the modified status info dict. On failure
              communicating with rethinkdb, returns `status_info` unmodified.
  
          Raises:
              Exception: if `status_info` is missing a required field, or a
                  `status_info['ttl']` is not a number greater than zero
          '''
          for field in 'role', 'ttl', 'load':
              if not field in status_info:
                  raise Exception(
                          'status_info is missing required field %s',
                          repr(field))
          val = status_info['ttl']
          if not (isinstance(val, float) or isinstance(val, int)) or val <= 0:
              raise Exception('ttl must be a number > 0')
          updated_status_info = dict(status_info)
          updated_status_info['last_heartbeat'] = r.now()
          if not 'first_heartbeat' in updated_status_info:
              updated_status_info['first_heartbeat'] = updated_status_info['last_heartbeat']
          if not 'host' in updated_status_info:
              updated_status_info['host'] = socket.gethostname()
          if not 'pid' in updated_status_info:
              updated_status_info['pid'] = os.getpid()
          try:
              result = self.rr.table(self.table).insert(
                      updated_status_info, conflict='replace',
                      return_changes=True).run()
              return result['changes'][0]['new_val'] # XXX check
          except:
              self.logger.error('error updating service registry', exc_info=True)
              return status_info