[asterisk-commits] murf: branch group/CDRfix5 r74512 - /team/group/CDRfix5/doc/tex/cdrbible.tex
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Wed Jul 11 08:43:47 CDT 2007
Author: murf
Date: Wed Jul 11 08:43:46 2007
New Revision: 74512
URL: http://svn.digium.com/view/asterisk?view=rev&rev=74512
Log:
The beginning of the CDR bible
Added:
team/group/CDRfix5/doc/tex/cdrbible.tex (with props)
Added: team/group/CDRfix5/doc/tex/cdrbible.tex
URL: http://svn.digium.com/view/asterisk/team/group/CDRfix5/doc/tex/cdrbible.tex?view=auto&rev=74512
==============================================================================
--- team/group/CDRfix5/doc/tex/cdrbible.tex (added)
+++ team/group/CDRfix5/doc/tex/cdrbible.tex Wed Jul 11 08:43:46 2007
@@ -1,0 +1,162 @@
+
+\section{The CDR Bible}
+
+This is description of a re-engineered version of the CDR system in Asterisk.
+
+The original CDR system originated in the days before call forwarding, and hasn't been
+updated as Asterisk adopted new features. Some changes to the CDR system were made
+in 1.4, but really, it seems like all the changes did for folks, was muck up currently running
+implementations. So, in that spirit, 1.6 (hopefully) will introduce a somewhat even more
+revamped CDR system that is guaranteed to break every current implementation.
+
+So, what's so great about the new stuff, and why is it worth the expense of
+re-implementation?
+
+First of all, it's guaranteed to capture all those conversations that result from linking two
+channels together for a conversation. Previous versions were spotty in this regard, when
+transfers or meetme's were involved.
+
+Next, it's more straightforward. It captures only "bridged" conversations-- where two channels
+(or more) are connected. It no longer captures one-sided conversations; for example, if a party calls
+into an asterisk system, and is presented with a menu, but hangs up before a choice is made,
+then no CDR is generated by Asterisk. (But you can cause one to be generated from the dialplan,
+which we will discuss later!) Also, it's more straightforward, in that you won't have to
+do as much experimentation and tweaking to make it work as you need it to. We can describe
+in a few short paragraphs how it's set up, and based on the expected behavior, you can
+write up your dialplan. And, when the stuff built into Asterisk gives you the "wrong" data,
+there is a way to fix things on the back end that will surely make you happy.
+
+\subsection{Terminology}
+
+First of all, let's understand the basic lingo, that Asterisk developers use,
+to describe their world. Along the way, I'll state the simple truths and laws that
+govern the CDR world.
+
+First of all, let's talk about CHANNELS. A channel is a communication pipe. Every device,
+whether it's making a call, or getting a call, whether it's hardware, or even just a software
+device, is connected to its very own channel. Thus, all human-to-human conversations
+involve two devices, and two channels.
+
+Next, let's talk about BRIDGES. A bridge is more of a concept than something physical,
+but what it does is connects two channels. It's takes the output of one channel, and
+funnels it into the input of the other channel, and vice versa for the output of the
+other channel. This provides a duplex communication channel that everyone loves
+in phone systems. One other factoid: We refer to the channel that is originating the
+conversation (the caller) as the "channel", and the channel that is getting the call (the callee),
+as the "peer". Bridges are formed by the Dial and Queue commands, for example. Meetme's
+run something that looks like a bridge; the same procedure for CDR generation is followed
+there, for MeetMe joining and leaving.
+
+Next, the common CDR. It's short for Call Detail Record (I think). Most folks pronounce
+the letters C.D.R, but personally, I'm an old LISP hacker, and pronounce it "cood-er",
+(Look up (car) and (cdr) in your Lisp manuals). CDR's are a standardized way to
+express call information, and form a database that can be used to bill folks for calls.
+CDR's contain several fields, like the exact times a call was started, answered, and
+then ended. It contains information about who placed the call, and who received the call.
+It may contain some account information, and some information about the duration of the
+call. An important fact is that a CDR struct can contain a list of user-defined
+variables (name/value pairs). You can attach as many variables to a CDR as you need.
+Here is a list of the fields in the CDR:
+\begin{itemize}
+ \item clid. The CallerID. in format "name"<number>
+ \item src. The CallerID number.
+ \item dst. The destination extension in the dialplan.
+ \item dcontext. The destination context in the dialplan.
+ \item channel. The name of the channel originating the call.
+ \item dchannel. The name of the channel getting the call.
+ \item lastapp. The name of the last application run.
+ \item lastdata. The arguments to the last applications run from the dialplan.
+ \item start. The time the originating channel was created, unless reset.
+ \item answer. The time the bridge was created. (Usually immediately after a phone is answered.)
+ \item end. The time the bridge completed. (Usually brought on by a hangup).
+ \item duration. The difference between the start and end times. In seconds.
+ \item billsec. The difference between the answer and end times. In seconds.
+ \item disposition. A number describing how the call completed. Asterisk only generates "ANSWERED" CDRs.
+ The possibilities are:
+ \begin{itemize}
+ \item NO ANSWER (value=0 or 4)
+ \item FAILED (value=1)
+ \item BUSY (value=2)
+ \item ANSWERED (value=8)
+ \end{itemize}
+ \item amaflags. A user-assigned status.
+ The possibilities are:
+ \begin{itemize}
+ \item OMIT (value=1)
+ \item BILLING (value=2)
+ \item DOCUMENTATION (value=3) (default value)
+ \end{itemize}
+ \item accountcode. A user assigned string, up to 20 characters.
+ \item uniqueid. A string, up to 32 characters, assigned to the channel.
+ \item linkedid. Filled in for most transfers, with the a hopefully common value. Its intention is to link
+ transferred conversations, where the transferrer and transferree have the same linkedid.
+ \item userfield. A user assigned string. up to 255 characters.
+\end{itemize}
+
+Now, let's discuss what a DIALPLAN is. It's a description of what Asterisk should
+do, in painful detail, when calls come in. It's basically a program that directs Asterisk
+in its operations. Someone has to write one (pretty much) for every installation of Asterisk.
+You might luck out, and get a system that will generate one for you, based on a web page
+or whatever, but no matter who writes it, it has to be written by someone or something.
+DialPlans come in three flavors: the ever present extensions.conf format, which is like
+writing code in Assembly format, AEL, which is a bit like C, and you can also write all
+or parts of the dialplan in any programming language you wish, and connect it to Asterisk
+via the AGI interface. Basically, a dialplan runs a sequence of APPLICATIONS and FUNCTIONS
+that allow Asterisk to do everything it does.
+
+\subsection{Principles of Operation}
+
+Not all useful calls into or out of an Asterisk box involve bridges. Some involve just
+(for example) someone calling in and listening to an announcement. This kind of thing
+is done by an Application in the dialplan. Because no bridge was
+formed, no CDR is normally generated, but if one is needed, a set of Functions
+can be used in the dialplan to generate a CDR with the fields set as you need.
+
+Now, let's dive into the facts of life, as far as CDR's are concerned.
+
+First, When a channel is created, a chunk of memory (a struct) is attached to the channel,
+which contains all the CDR information. At this point, the "Start" time is set to the
+current time, when the channel was created. The channel name and other fields are
+also filled in at this time. Let's call this the CDR struct.
+
+Next. just before a bridge is formed, a new CDR struct is formed, and it is associated
+with the bridge. The channel CDR struct fields are updated from the channel, and then
+the entire channel CDR struct is copied into the bridge CDR struct. Notice that I use the
+term "channel" here, and not "peer". A few fields are filled in from the peer (like the
+destination channel name). The Answer time is set in the bridge CDR struct to the current
+time.
+
+After the conversation is finished (one side or the other hangs up), and the bridge
+ends, then the "end" time in the bridge CDR struct is set, and the CDR is posted
+to the database backends. After it is posted, it is freed and its memory is reclaimed
+for other purposes.
+
+During the process of being pushed into a database of some kind, the user has one last
+chance to make amendments to the data. Using configuration/mapping files for the database,
+the user can substitute one CDR field for another, leave out fields if such is desired,
+and add fields to the database from the CDR. See the sections describing the mappings.
+We will outline some methods to do this in detail, later on in this document.
+
+There. That's it. Simple, eh?
+
+While it sounds so simple, so straightforward, let me explain a few reasons for WHY
+it's being done that way. Firstly, Keeping a separate CDR for the bridge is a good idea,
+because previously, the CDR on the channel stored the information, and was subject to all
+sorts of changes and manipulations as the call progressed. If a transfer occurred,
+an answer time might get updated from a separate conversation, for example.
+
+Updating a CDR once from the channel occurs before the bridge forms: this is a good idea,
+because previously, several ways existed to update this information, and hangups and hangup extensions,
+as well as macro calls could cause inexplicable changes before the CDR was posted.
+Some users used this behavior to subtily modify the CDR contents in highly non-forward
+compatible ways!
+
+\subsection{Making Your Own CDRs}
+\subsection{Suppressing Asterisk-Generated CDRs}
+\subsection{Gotchas and Complications}
+\subsection{Backend Mappings}
+
+
+
+
+
Propchange: team/group/CDRfix5/doc/tex/cdrbible.tex
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/group/CDRfix5/doc/tex/cdrbible.tex
------------------------------------------------------------------------------
svn:keywords = Author Id Date Revision
Propchange: team/group/CDRfix5/doc/tex/cdrbible.tex
------------------------------------------------------------------------------
svn:mime-type = text/plain
More information about the asterisk-commits
mailing list