Class: DtraceConsumer

Inherits:
Object
  • Object
show all
Defined in:
lib/dtraceconsumer.rb

Overview

A DtraceConsumer provides access to the data produced by the running D program. Having compiled and executed a D program, you typically create a DtraceConsumer, and wait for data.

You can either wait indefinitely for data, or consume all the data waiting and then stop: if your D program consists of only of aggregations, returned by printa() actions in the END block, this will be the best approach. If you have a mix of trace() and printf() actions elsewhere, you’ll probably want to wait until interrupted, the D program itself exits, or your program decides it has collected enough data.

The two approaches are implemented by the consume and consume_once methods.

The consume and consume_once methods accept a block to which is yielded complete DtraceData objects, one for each probe which fires.

You must have already started tracing when you call consume or consume_once, so the general structure will look like:

t = Dtrace.new
progtext = "..."
prog = t.compile progtext
prog.execute
t.go 
c = DtraceConsumer.new(t)
c.consume_once do |d|
  # handle DtraceData objects
  # ...
  # get bored:
  c.finish
end

Instance Method Summary collapse

Constructor Details

#initialize(t) ⇒ DtraceConsumer

Returns a new instance of DtraceConsumer.



42
43
44
45
46
47
48
49
 
# File 'lib/dtraceconsumer.rb', line 42

def initialize(t)
  @t = t
  @done = false
  @types = []

  @drophandler = nil
  @errhandler = nil
end

Instance Method Details

#consume(*types, &block) ⇒ Object

Waits for data from the D program, and yields the records returned to the block given. Returns when the D program exits.

Pass a list of classes to restrict the types of data returned, from:

  • DtraceRecord

  • DtracePrintfRecord

  • DtraceAggregateSet

  • DtraceStackRecord



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/dtraceconsumer.rb', line 138

def consume(*types, &block)
  filter_types(types)
  @t.buf_consumer(buf_consumer)
  begin
    while(true) do
      @t.sleep
      work = @t.work(probe_consumer, rec_consumer(block))
      if (@done || work > 0)
        break
      end
    end
  ensure
    @t.stop
    @t.work(probe_consumer)
  end
end

#consume_once(*types, &block) ⇒ Object

Yields the data waiting from the current program, then returns.

Pass a list of classes to restrict the types of data returned, from:

  • DtraceRecord

  • DtracePrintfRecord

  • DtraceAggregateSet

  • DtraceStackRecord



165
166
167
168
169
170
 
# File 'lib/dtraceconsumer.rb', line 165

def consume_once(*types, &block)
  filter_types(types)
  @t.buf_consumer(buf_consumer)
  @t.stop
  @t.work(probe_consumer, rec_consumer(block))
end

#drophandler(&block) ⇒ Object

Provide a proc which will be executed when a drop record is received.



101
102
103
104
105
106
107
108
 
# File 'lib/dtraceconsumer.rb', line 101

def drophandler(&block)
  @drophandler = block
  @t.drop_consumer(proc do |drop|
                     if @drophandler
                       @drophandler.call(drop)
                     end
                   end)
end

#errhandler(&block) ⇒ Object

Provide a proc which will be executed when an error record is received.



112
113
114
115
116
117
118
119
 
# File 'lib/dtraceconsumer.rb', line 112

def errhandler(&block)
  @errhandler = block
  @t.err_consumer(proc do |err|
                    if @errhandler
                      @errhandler.call(err)
                    end
                  end)
end

#finish ⇒ Object

Signals that the client wishes to stop consuming trace data.



122
123
124
125
 
# File 'lib/dtraceconsumer.rb', line 122

def finish
  @t.stop
  @done = true
end