bneradt commented on a change in pull request #7014: URL: https://github.com/apache/trafficserver/pull/7014#discussion_r457506212
########## File path: doc/admin-guide/plugins/memory_profile.en.rst ########## @@ -0,0 +1,106 @@ +Memory_profile Plugin +********************* + +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. + + +This plugin listens for plugin msgs and invokes jemalloc control +operations. + +Installation +============ + +Add the following line to :file:`plugin.config`:: + + memory_profile.so + +In addition, |TS| must be able to read jemalloc configuration +information either through the ``JEMALLOC_CONF`` environment variable +or via the string sym linked to ``/etc/malloc.conf``. + +For example, if the string below is in ``JEMALLOC_CONF`` or in the sym link string, it +enables profiling and indicates that the memory dump prefix is ``/tmp/jeprof``.:: + + prof:true,prof_prefix:/tmp/jeprof + +Details on configuration jemalloc options at `<http://jemalloc.net/jemalloc.3.html>`. +Changes to the configuration in ``JEMALLOC_CONF`` or ``/etc/malloc.conf`` require a process +restart to pick up. + +Plugin Messages +=============== + +The plugin responds to the following mesages sent via traffic_ctl. + +Message Action +========== =================================================================================== +activate Start jemalloc profiling. Useful if prof_active:false was in the configure string. + +deactivate Stop jemalloc profiling. + +dump If profiling is enabled and active, it will generate a profile dump file. + +stats Print jemalloc statistics in traffic.out + +The command below sends the stats message to the plugin causing the current statistics to be written to traffic.out:: + + traffic_ctl plugin msg memory_profile stats + +Example Usage +============= + +If your run time configuration string is:: + + prof:true,prof_prefix:/tmp/jeprof:prof_active:false + +|TS| has started without profile sampling started. Perhaps you didn't want to profile the start up phase of |TS|. To start +you need to send the activate message to the plugin:: + + traffic_ctl plugin msg memory_profile activate + +If your run time configuration string does not indicate that the profiling is not started (e.g. the prof_active field is missing or set to true), you do not +need to send the activate message. + +After waiting sometime for |TS| to gather some memory allocation data, you can send the dump message:: + + traffic_ctl plugin msg memory_profile dump + +This will cause a file containing information about the current state of the |TS| memory allocation to be dumped in a file prefixed +by the value of prof_prefix. In this example, it would be something like ``/tmp/jeprof.1234.0.m0.heap``, where 1234 is the process id +and 0 is a running counter indicating how many dumps have been performed on this process. Each dump is independent of the others +and records the current stat of allocations since the profiling was activated. The dump file can be processed by jeprof +to get text output or graphs. Details of how to use jeprof are in the man pages or `<https://manpages.debian.org/unstable/libjemalloc-dev/jeprof.1.en.html>`. + +You may want to send the dump message periodically to analyze how the |TS| memory allocation changes over time. This periodic dump can also be achieved by setting the +``lg_prof_interval`` option in the run time configuration string. + +If the profiling is taking a significating amount of processing time and affecting |TS| performance, send the deactivate message to turn off profiling.:: + + traffic_ctl plugin msg memory_profile deactivate + +Send the stats message to cause detailed jemalloc stats to be printed in traffic.out. These stats represent actvitiy since the start of the |TS| process.:: Review comment: We probably don't want the period before the colon. Also on line 92. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
